docs(local): record verified client key migration and service startup (#237)

2026-09-07 17:45:38 +08:00
parent 9a10d82cf4
commit 9d5242b371
4 changed files with 24 additions and 13 deletions
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Architecture-and-Code-Map
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Architecture-and-Code-Map.-
-wiki_revision: 0b9d4e6e0e97f495d19a53e1aa0ecea3a66ba495
-synchronized_at: 2026-09-07T09:27:49Z
+wiki_revision: 9d3b3f2683b5c77f3fd6601057e64c2cda773a51
+synchronized_at: 2026-09-07T09:43:41Z
 <!-- gitea-wiki-mirror:end -->

 # 架构与代码地图
@@ -336,7 +336,7 @@ PddProductDetailCollector

 ## 客户端密钥访问架构（#237）

-代码基线 `71f7751`（含用户确认的默认 HTTP/HTTPS 兼容），2026-09-07 完成 Server/Web 代码与隔离测试；实际迁移、权限写入和部署尚未执行，不表示现有线上能力。
+代码基线 `71f7751`（含用户确认的默认 HTTP/HTTPS 兼容），2026-09-07 完成 Server/Web 代码与隔离测试；本机迁移、管理员菜单写入与 Server/Web 启动已于 2026-09-07 授权完成，真实 HTTP 管理列表和模块目录加载通过；线上仍未部署。

 - `server/app/goauto/clientkey` 管理独立密钥、授权及审计；`clientapi/routes.go` 的显式 Inventory 将 `/api/client/v1` 映射到既有业务处理器，绝不转发任意 Admin 路由。
 - `clientapi/gateway.go` 默认接受 HTTP 与 HTTPS，无协议开关或转发协议头门禁，按 Bearer 密钥、模块及能力顺序校验，每次请求读取数据库，无授权缓存。`common/clientprincipal` 传递独立客户端身份，不生成或伪装管理员 JWT。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Business-Rules-and-Glossary
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Business-Rules-and-Glossary.-
-wiki_revision: 17e346d6e9398abe2188280112fc04d88fd10d88
-synchronized_at: 2026-09-07T09:27:54Z
+wiki_revision: 2a9334053de83a9a0525af074755f67964b48a29
+synchronized_at: 2026-09-07T09:43:46Z
 <!-- gitea-wiki-mirror:end -->

 # 业务规则与术语
@@ -447,7 +447,7 @@ synchronized_at: 2026-09-07T09:27:54Z

 ## 客户端密钥与可编辑模块授权（#237）

-以下为提交 `71f7751` 已实现、尚待实际迁移与部署的规则。
+以下为提交 `71f7751` 已实现的规则；2026-09-07 本机已迁移并验证管理页面可用，线上尚未部署，真实客户端密钥执行闭环尚未验证。

 - 仅管理员创建、查看、编辑授权或停用密钥。首版不提供密钥改名、到期、轮换、恢复启用、删除或任意接口授权。
 - 模块选择复用“采集采购/采采管理”现有 12 个业务模块；分组勾选只影响当前子模块，新菜单不会自动获得授权。客户端密钥管理、系统账号权限及支付不在可授权模块中。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Android-Agent-API-Contract
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract.-
-wiki_revision: 36f6f6081f0cfdfd8a4a395a27eaef0a6cd88cda
-synchronized_at: 2026-09-07T09:28:25Z
+wiki_revision: 59853b796dc787d6af4b6ca3a9c1ae3156cc7152
+synchronized_at: 2026-09-07T09:44:13Z
 <!-- gitea-wiki-mirror:end -->

 # MVP 共享 API 契约
@@ -870,7 +870,7 @@ Agent 携带既有 Token（可已失效）及恢复码重新调用注册接口

 ## 客户端 API 与管理员密钥管理（#237）

-实现基线 `71f7751`；以下接口已通过隔离测试，尚未完成真实迁移/部署联调。Android 接口不变。
+实现基线 `71f7751`；以下接口已通过隔离测试；2026-09-07 本机 MySQL 迁移及管理员通过 HTTP 读取列表、模块目录已验证，真实密钥创建/编辑/停用及业务访问仍未联调，线上尚未部署。Android 接口不变。

 ### 管理接口

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Deployment-and-Operations
 wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Deployment-and-Operations.-
-wiki_revision: e936b9e3a5850dea31c139c09e8aca8584d9a6dd
-synchronized_at: 2026-09-07T09:28:03Z
+wiki_revision: f951dbc8b6a555cbf8f44cda073910406ba55191
+synchronized_at: 2026-09-07T09:43:56Z
 <!-- gitea-wiki-mirror:end -->

 # 部署与运维
@@ -73,12 +73,23 @@ Provider 故障日志只允许记录调用关联 ID、操作类型、耗时、

 ## 客户端密钥部署与验证（#237）

-实现基线 `71f7751`；2026-09-07 仅完成代码及隔离测试，尚未执行实际数据库迁移、权限写入、服务重启或部署。
+实现基线 `71f7751`；2026-09-07 已按用户授权完成本机 MySQL 迁移、管理员菜单写入和 Server/Web 构建重启；管理页面 HTTP 列表与模块加载已验证。线上仍未部署。

 - 发布前须单独授权追加迁移 `server/cmd/migrate/migration/version-local/1788798000000_client_api_key.go`，按既有迁移流程创建 client_api_key、client_api_key_audit 和“采采管理/客户端密钥”管理员菜单。前置父菜单必须存在；不应以赋予普通用户管理员角色代替迁移或权限核验。
- 用户于 2026-09-07 明确确认默认兼容 HTTP/HTTPS、不设开关并接受明文风险；部署本版本并执行迁移后，现有 `http://185.216.248.75:9527` 可以使用客户端密钥管理及客户端 API。当前并未实际部署，不能据此宣称线上已经可用。HTTP 会明文传输密钥和业务数据，仍建议使用 HTTPS。
+- 用户于 2026-09-07 明确确认默认兼容 HTTP/HTTPS、不设开关并接受明文风险；部署本版本并执行迁移后，现有 `http://185.216.248.75:9527` 可以使用客户端密钥管理及客户端 API。本机已部署验证，不能据此宣称线上已经可用。HTTP 会明文传输密钥和业务数据，仍建议使用 HTTPS。
 - 客户端密钥功能不依赖 GOAUTO_TRUST_FORWARDED_PROTO、X-Forwarded-Proto 或 Agent HTTP 例外。既有其他路由的协议和代理配置保持不变；不伪造协议头，不新增明文放行开关。
 - 代理、APM、应用日志均不得记录 Authorization、创建响应 secret 或原始业务载荷。应用对两类客户端密钥路由跳过旧请求/响应正文日志，使用专用元数据审计；实际代理日志脱敏仍须部署验收。
 - 请求审计 status=0 可能表示在途、进程中断或结果审计更新失败；先按请求关联号核对业务结果，不自动重试采购、采集、同步等操作。停用阻止后续认证，不保证取消已开始的业务操作。
 - 隔离验证：Server `go test ./app/goauto/clientkey ./app/goauto/clientapi ./cmd/migrate/migration/version-local`；Web `pnpm exec jest tests/unit/client-keys.spec.js --runInBand` 与 `pnpm run build:prod`。浏览器模拟入口 `/tests/fixtures/client-keys.html` 仅由本地 Vite 开发服务承载，使用内存模拟请求和无效示例密钥，不连接真实数据库，不证明线上鉴权已验收。
 - 真实部署验收须另行验证实际 HTTP/HTTPS 入口、管理员创建/编辑/停用、普通用户拒绝、读写/独立动作隔离、停用后的后续请求拒绝及日志无密钥；任何真实业务执行继续按独立授权范围进行。
+
+
+## Windows 本机运行目录与 #237 迁移验证（2026-09-07）
+
+- Supervisor 实际配置 `D:/supervisor/programs/goauto.conf`；程序仅 `goauto-admin-api` 和 `goauto-admin-ui`。从已有干净工作区 `D:/OPC/goauto-worktrees/main-runtime` 的 main 分支运行；源码运行基线 `ac3c63e`，版本化启动模板更新提交 `9a10d82`。
+- 原目录 `D:/OPC/goauto` 的用户改动保持原样；本机敏感配置继续读取 `D:/OPC/goauto/config.yaml`，不复制凭据到运行工作区或版本库。数据库 `127.0.0.1:3307/goauto`，API `http://127.0.0.1:8010`，Web `http://127.0.0.1:9527`。
+- API 命令：`pwsh.exe -NoLogo -NoProfile -File "D:/OPC/goauto-worktrees/main-runtime/scripts/start-server.ps1" -ConfigPath "D:/OPC/goauto/config.yaml" -SkipMigration`；Web 同目录 `scripts/start-web.ps1` 与相同 ConfigPath。已验证无需 ExecutionPolicy Bypass。
+- 真实迁移必须单独授权并先确认唯一待执行版本；常驻 API 加 `-SkipMigration`，日常重启不自动执行未来待审核迁移。#237 迁移 `1788798000000_client_api_key.go` 已执行，sys_migration 记录 `1788798000000`、两张密钥表及管理员菜单已回读；其他角色未新增菜单关联。任务启停状态未改。
+- 范围明确的服务控制：`D:/supervisor/supervisord.exe -c D:/supervisor/supervisord.conf ctl status goauto-admin-api goauto-admin-ui`，启动/停止/重启将 status 分别替换为 start/stop/restart。不得为了 GoAuto 重启整个 Supervisor 或其他项目。配置内容变化后需重新读取配置；本次调用 `supervisor.reloadConfig`，再对上述两个程序定向 start，已通过进程命令行核对新目录。
+- 日志：`D:/supervisor/logs/goauto-admin-api.log`、`D:/supervisor/logs/goauto-admin-ui.log`；对外分享只能保留脱敏结构摘要。迁移输出不得暴露凭据或业务原文。
+- 管理员刷新页面后可进入 `http://127.0.0.1:9527/#/client-keys/index`；菜单缓存未更新时重新登录。已验证列表空态、创建弹窗加载 12 模块及 HTTP 风险提示；未实际创建密钥，真实客户端读写及停用闭环仍待范围明确的验证。线上 GoAuto/Nginx 未重启或发布。