For AI agents: the complete documentation index is available at https://payhon.github.io/AppKernia/llms.txt, the full documentation bundle is available at https://payhon.github.io/AppKernia/llms-full.txt, and this page is available as Markdown at https://payhon.github.io/AppKernia/guide/remote-client.md.
AppKernia

多服务器认证与远程 CLI

本页描述当前源码中的功能；已有公开预览制品不保证包含这些命令。安装渠道和下载链接不变，参见 安装与部署。

akone 可以只作为客户端运行，不要求本机启动 serve、初始化管理员或创建数据库。先在目标服务器的管理后台创建 API Client，生成 AppSecret，并为 Agent 调用绑定真实用户、配置客户端权限和必要的应用授权。权限不会超过客户端与绑定用户的交集。

配置与切换

akone auth configure --profile production \
  --server https://api.example.com --client-id ak_xxx
# 终端隐藏输入 AppSecret，不放入命令参数

akone auth configure --profile local \
  --server http://localhost:8080 --client-id ak_yyy
akone auth list
akone auth use production
akone auth status --profile production
akone api call getAdminDashboardSummary --profile production

第一组配置自动成为默认；新增不会切换。选择顺序为 --profile > AK_PROFILE > 当前默认。名称不存在时直接失败，不会访问其他服务器。auth status 实际交换 Token，输出服务器、Client ID 和认证结果，不输出 Secret/Token；认证成功不代表拥有所有业务权限。

Origin 可以带端口，例如 https://api.example.com:8443，但不能包含 /api、查询、片段或 URL 内嵌凭据。公网必须 HTTPS，HTTP 仅限 localhost/loopback；证书必须有效，不提供跳过验证开关，也不跟随重定向。

api call --server URL 只能确认已选凭据的地址，不能把 Secret 转发到另一个域名。连接另一台服务器应配置另一组 Profile。同名 Profile 更换服务器必须加 --replace，并重新提供完整凭据。

akone auth configure --profile production --replace \
  --server https://new-api.example.com --client-id ak_new
akone auth remove local --yes

删除只移除本地配置，不撤销服务器客户端；删除默认配置后必须显式选择下一台服务器，不会自动切换。要撤销访问，应在目标服务器后台撤销 Secret、禁用客户端或解除用户绑定。

自动化与 AI Agent

优先由人工配置 Profile，让 Agent 显式携带 --profile production，不把 AppSecret 放进提示词或工具参数。非交互初始化可由秘密管理器向 auth configure ... --secret-stdin 的标准输入传入 Secret。

不使用文件时，由 CI 的秘密注入机制同时设置以下三个变量：

  • AK_SERVER_URL：目标服务器 Origin。
  • AK_CLIENT_ID：该服务器签发的 Client ID。
  • AK_CLIENT_SECRET：对应 AppSecret。

随后直接运行 akone api call getAdminDashboardSummary。这组三元组仅在本次进程内生效，不落盘；部分提供会失败，也不能与 --profile 或 AK_PROFILE 同时使用。不会从文件补齐缺失字段。

akone api list
akone api describe getAdminDashboardSummary
akone api call getAdminDashboardSummary --profile production \
  --query range=7d --timeout 20s

api list/describe 输出二进制内嵌的 OpenAPI，stderr 明确标注来源；它不是远程发现结果。远程旧版本或 SQLite 未实现的接口返回错误，不会改用本机或重试写请求。成功退出码为 0，运行/认证失败为 1，参数用法错误为 2；业务错误使用稳定 CLI.AUTH.* 码，AK_LOCALE=en-US 切换可见文案。

凭据文件与迁移

默认文件为系统用户配置目录下的 AppKernia/credentials.json；可通过 --credentials-file 或 AK_CREDENTIALS_FILE 指定。该文件与服务端 YAML 独立。文件包含 AppSecret 明文，必须由当前用户独占：Unix 文件权限 0600，Windows 放在仅当前用户可读的 ACL 目录，禁止提交 Git。

旧单配置只读时映射为 default；首次修改自动保存原字节到 credentials.json.v1.bak，再原子迁移为多 Profile 格式。备份也含 Secret，应同等保护。符号链接、非普通文件、不安全权限、冲突备份均被拒绝；多个 CLI 修改通过文件锁串行。

远程部署与数据库边界

服务器按 部署指南 保持监听回环地址，经 TLS 反向代理公开；客户端配置代理的 HTTPS Origin，不配置内部监听地址。代理应直接提供 API，不应将认证请求重定向到其他域名。CIDR 白名单基于服务实际观察到的连接 IP；经过代理时应结合网关访问控制，不要假定任意转发头可信。

当前源码的 SQLite v2 支持 API Client 管理、Token 交换、用户绑定、权限/应用授权及三个 Dashboard Agent 接口。将服务端 features.api_clients 或 AK_API_CLIENTS_ENABLED 设为 true 以显示客户端功能。其余依赖的管理页面数据源与内容/通知模块尚未完整支持 SQLite；已有管理员可通过相同管理 API 配置客户端，不应把整个管理 UI 标为已验收。

服务端 SQLite 升级前停服备份；回退同时恢复旧二进制和升级前数据。客户端 Profile 不改变服务端数据库，也不参与插件进程的 Bootstrap/TLS。插件远程管理命令仍在后续实施中，当前 plugin dev 不接受远程 Profile。