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: e1a414ee157174e28273068275679a00d8781f95 synchronized_at: 2026-09-02T09:36:32Z

部署与运维

当前线上拓扑

• 外部入口：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。