goauto/docs/13-deployment-and-operations.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Deployment-and-Operations wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Deployment-and-Operations.- wiki_revision: df033d06fd94a4b02a447a27ced8d711521342f3 synchronized_at: 2026-09-08T02:23:08Z

部署与运维

当前线上拓扑

• 外部入口：http://185.216.248.75:9527，Nginx 同时承载 Admin 静态资源并反向代理 GoAuto API。
• GoAuto 服务监听：127.0.0.1:8010。
• 常驻服务：systemd goauto.service。
• 工作目录：/home/goauto/current，指向 /home/goauto/releases/<发布标识>。
• 服务配置：/home/goauto/current/config/settings.yml；敏感环境变量由 /etc/goauto/goauto.env 提供，不写入 Git、Wiki、工单或日志。
• Agent APK 私有目录：相对工作目录的 var/goauto-agent-releases；下载必须通过已认证接口。

Agent HTTP 例外

服务端生产模式默认要求 Agent 使用 HTTPS。当前线上入口只有 HTTP，因此经 #181 用户明确确认，在 /etc/goauto/goauto.env 设置：

GOAUTO_ALLOW_INSECURE_AGENT_HTTP=true

该开关只放宽全部 /api/agent/v1/**，包括注册、心跳、采集、采购、Agent 版本检查与下载；不放宽 Admin、PDD、SYB、OCR 或其他第三方地址的安全约束。HTTP 会明文传输 Device Token、任务内容、设备状态和执行结果。后续启用 HTTPS 后应删除该变量或设为 false。

GOAUTO_TRUST_FORWARDED_PROTO=true 只表示信任受控反向代理传入的 X-Forwarded-Proto: https，不能把实际 HTTP 请求视为加密链路，也不能替代上述显式 HTTP 开关。

发布与验证

1. 在本地完成服务端测试/构建和 Android 单测/APK 构建，记录提交、versionCode、SHA-256 与大小。
2. 创建新的 /home/goauto/releases/<发布标识>，复制服务端二进制、Web 静态资源和非敏感配置；保留旧发布目录用于回滚。
3. 原子切换 /home/goauto/current 后重启 goauto.service，确认 systemctl is-active goauto.service 为 active，并从外部入口验证 API。
4. 上传 APK 到 Admin Agent 版本并按需设为当前；服务端解析 Manifest，校验 versionCode 唯一性并保存 SHA-256。
5. 真机安装前确认设备没有运行中的任务。Android 系统安装确认仍由人工完成，Agent 不静默安装。

发布、重启、设置当前 Agent 版本和真机安装都属于高风险操作，必须有对应工单和人工确认。不得在部署过程中执行付款、创建订单或清理生产数据。

API 长请求超时约束

Admin 蝦皮规格 AI 匹配会同步等待外部 Provider：Provider 配置允许 3～600 秒，复合的一键匹配共享 600 秒总预算，Admin 客户端等待 610 秒。因此服务端 settings.application.writetimeout 必须至少为 620 秒，受版本管理的标准配置固定为 620；启动时低于该值必须明确失败，禁止以 2 秒等短写超时运行，否则连接会在领域错误返回前被截断并表现为代理 502。反向代理的读/发送超时也必须大于服务端窗口。

Provider 故障日志只允许记录调用关联 ID、操作类型、耗时、上游 HTTP 状态码或网络错误分类；不得记录 API Key、Authorization、Provider URL、模型输入、候选规格、商品原始内容或响应正文。Provider 失败时接口返回 HTTP 503 与 AI_MATCHING_UNAVAILABLE，供 Admin 显示安全中文提示。

回滚

服务异常时把 /home/goauto/current 切回上一已验证发布目录并重启 goauto.service，随后复核服务状态和 Agent 接口。不要删除当前或历史 APK/发布目录来代替回滚；数据库变化如需回退必须单独评估。

蝦皮规格自动匹配任务运维（#195）

• 迁移 1788290000000_shopee_spec_auto_match.go 创建运行与工作状态表，并幂等写入 sys_job.invoke_target=GoAutoShopeeSpecAutoMatch。首次部署状态为关闭，迁移重跑不会覆盖管理员后来修改的 Cron、参数或启停状态。
• 默认 Cron 为 0 15 * * * *（每小时第 15 分钟），默认 batchLimit 为 20，合法范围 1～100。上线后先保持关闭，在 Admin 蝦皮商品列表手动执行小批次并核对运行摘要和映射，再由管理员在定时任务页明确启用。
• 定时和手动触发共享数据库唯一活动槽。看到“已有自动匹配正在运行”属于正常互斥结果；运行租约超过 30 分钟会在下次触发时安全释放并把旧运行标记失败。处理每个商品前会续租。
• Provider 临时失败的商品至少 60 分钟后重试，最多 3 次；低置信度或无结果在输入指纹不变时不会重复调用。排错优先查看 shopee_spec_auto_match_run 的结构化计数与脱敏错误，以及 shopee_spec_auto_match_work_item 的状态、尝试次数、下次尝试时间和租约；不得输出或复制 API Key、Provider 原始响应、商品原始 JSON 或个人数据。
• 紧急回退只需关闭系统任务并停止使用 Admin 手动入口；保留运行记录和既有已确认映射用于审计，不删除数据，也不回滚 #194。

SYB 异常规格 AI 定时任务（#198）

• 追加迁移 1788354164329_syb_spec_ai_parse.go 创建 AI 确认字段、syb_spec_ai_parse_run、syb_spec_ai_parse_work_item，并幂等写入 sys_job.invoke_target=GoAutoSYBSpecAIParse。
• 系统任务默认关闭，默认 Cron 为每小时第 5 分钟、参数 {"batchLimit":20}；迁移重跑不得覆盖管理员后续修改的 Cron、参数或启停状态。建议先运行该任务，再由默认第 15 分钟的 #195 完成蝦皮到 PDD 的规格匹配。
• 多实例通过可空唯一活动槽和租约保证全局单批运行；逐行工作项按输入指纹去重。Provider 临时失败至少 60 分钟后重试且最多 3 次，低置信度/无结果在输入不变时不重复调用。
• 上线顺序为：备份数据库、执行追加迁移、发布服务并保持任务关闭、核验表/字段/任务种子，再由管理员决定是否启用。排错只查看运行计数、工作状态和脱敏错误，不输出 API Key、Provider 原始响应、完整 RawJSON 或订单数据。

定时任务执行历史运维（#199）

• 发布 #199 时先备份数据库，再执行追加迁移 1788357000000_sys_job_execution_log.go，随后发布服务与 Web。迁移创建 sys_job_execution_log、登记 GET /api/v1/sysjob/:id/execution-logs，并只为原本绑定隐藏菜单 JobLog 的角色写入精确读取权限；菜单缺失时迁移明确失败，不扩大角色授权。
• 服务启动会将上次进程遗留的 running 执行记录标记为 interrupted。该恢复依赖当前线上每个数据库只运行一个调度器实例；扩展为多调度器前必须另建工单引入实例租约，不能直接复用此判断。
• 排错从 Admin 定时任务页单选任务后进入“日志”，按状态和开始时间查询。记录只含稳定错误码和脱敏摘要；需要定位细节时查看受控服务日志，不得把任务参数、Provider 配置/响应、密钥或业务原始数据复制进执行历史。
• 当前没有执行历史删除接口和自动保留策略；删除定时任务不删除历史。数据库容量治理需要另建工单评估。#198 的 GoAutoSYBSpecAIParse 在 #199 发布和迁移后仍保持关闭，启用必须由管理员另行确认。

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

实现基线 71f7751；2026-09-07 已按用户授权完成本机 MySQL 迁移、管理员菜单写入和 Server/Web 构建重启；管理页面 HTTP 列表与模块加载已验证。2026-09-08 经用户授权，线上已发布 Server/Web 基线 d403f3b，执行迁移 1788798000000 并重启 GoAuto/Nginx；迁移记录、两张密钥表、仅管理员菜单关联已回读。HTTP 页面与健康检查通过；未登录管理请求 HTTP 200、业务码 401。真实密钥创建及客户端业务读写闭环尚未验证。

• 发布前须单独授权追加迁移 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。2026-09-08 线上部署及未登录拒绝检查已通过，真实密钥读写验收仍待进行。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 风险提示；未实际创建密钥，真实客户端读写及停用闭环仍待范围明确的验证。本节为 2026-09-07 本机验证记录；线上已于 2026-09-08 另行授权发布，见上节。