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: cc642ebfa65f429100779e40560a59174ab877a0 synchronized_at: 2026-09-22T02:56:36Z

部署与运维

当前线上拓扑

• 外部入口：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秒；#254未部署前仍适用，部署后详情入口改用下节动态预算。因此服务端 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 另行授权发布，见上节。

蝦皮详情匹配等待与回读（#254）

实现绑定 9088e6b（2026-09-10，分支 fix/254-match-loading）；已通过合成数据测试，尚未合并 main 或发布线上。

• 本次只完成代码构建与合成测试，未改线上配置、AI设置、常驻服务或Nginx；部署与重启需另行授权。
• 详情匹配新窗口是后端 2T+10 秒、Web POST 2T+20 秒。当前默认API最低写超时校验仍为620秒，这是历史最低值，不保证容纳所有动态预算；发布前读取实际 AI timeoutSeconds、application.writetimeout 和生效代理配置核对。
• 建议API写超时至少为 2T+30 秒，且仍满足原最低620秒；代理读/发送超时需留足对应窗口。T=60/180时原620秒足够容纳应用预算；T=600时至少需要1230秒API写超时及适当更长的代理窗口。不得仅设置较大的AI超时却忽略传输层更早截断。
• 上述是发布核对要求，不是本单已修改/验证线上代理的结论。超大T带来长连接占用，不能用关闭超时来代替正确预算。新增失败回读不代表必须延长任何线上请求。
• 必须配套发布 Server/Web；仅上新版Web连接旧Server时，因缺失派生预算会提示等待时间不可用并停止匹配。原Android不需升级。

本地 Supervisor 与局域网访问

本机开发/联调环境由 D:\supervisor\programs\goauto.conf 分别启动 GoAuto API 与 Admin Web；实例配置只负责调用项目脚本，端口读取 D:\OPC\goauto\config.yaml。

• API 由 scripts/start-server.ps1 启动并监听所有网卡的 ports.server。
• Admin Web 由 scripts/start-web.ps1 启动，监听 0.0.0.0 的 ports.web，因此同一局域网设备可通过 http://<本机局域网IP>:<web端口>/ 访问。
• 浏览器使用同源相对 API；Vite 将 /api 与 /static 代理到本机 127.0.0.1:<server端口>，避免局域网客户端错误访问自身的 127.0.0.1。
• 修改脚本或配置后，只需重启 Supervisor 的 goauto-admin-ui；API 未变化时无需重启 goauto-admin-api。若局域网仍无法连接，检查 Windows 防火墙是否允许 ports.web 的 TCP 入站。

SYB 订单号回填 worker 部署与排错（#305）

代码绑定 e89de1a（2026-09-18），基于 #306 的07a3817；本节是部署要求，不表示已发布或业务库已迁移。

1. 另行取得明确目标环境的数据库迁移、权限对账和发布授权。核对 #306 的1789800100000金额列前置；本单追加1789800200000_purchase_order_writeback.go，建立purchase_order_writeback、purchase_order_writeback_command、purchase_order_writeback_lease三表和单例行，不改任务/付款事实，不排入历史回填、不修改定时任务开关。
2. 配套构建并发布Server/Web，沿用现有启动权限对账为管理员/采购员登记POST /api/admin/v1/purchase-tasks/syb-order-writeback。不新增角色、菜单或支付门槛。旧常驻实例使用SkipMigration时，仅重启并不能替代授权迁移。
3. API启动后每数据库恢复一个3秒轮询的持久队列worker，独立于Admin定时任务列表；只处理已排入pending及租约过期running。正式采购结果、人工订单回填成功/同号回放会排队；历史补偿仅用户勾选发起。部署重启后已有pending会执行真实SYB写入，必须包含在发布授权范围内。
4. 全局租约2分钟；会话恢复预算25秒，每次外部读/写20秒（只读客户端重试亦受该context限制），写前再次核验租约。崩溃恢复只回读，不盲目重写；unknown不自动重试，等租约到期再人工核对/补偿。同目标其他未确认写入先解决，不能删除记录规避保护。
5. 排错先看采购管理的“SYB 单号回填”状态、脱敏原因、完成时间；需要结构诊断时查询记录的taskId/status/attempt_count/error_code/lease_expires_at，不输出单号、Cookie或完整原始响应。SYB会话失败应先恢复既有登录，再勾选失败任务补偿；按钮受理不等于SYB成功。conflict只核对，不强制覆盖。
6. 不执行真实支付；实付金额只存Admin，SYB请求cost固定0。停止新版API可停止新轮询，但不保证已发送远端请求取消；回滚保留追加表和未知状态，不删除记录、不回退采购事实。迁移/多实例MySQL/真实SYB端到端仍需授权验收。

#305/#306 线上发布验证（2026-09-18）

用户授权合并main、迁移并发布线上；main已快进至7e257ca（包含#306及#305），Server/Web从该提交重新构建。此前线上RELEASE记录60c7526；新发布目录为/home/goauto/releases/20260918-7e257ca-305，current已原子切换，goauto.service重启、Nginx校验及reload成功。先前各节“未部署”是对应提交阶段记录，本节为后续发布事实。

• 迁移前51个版本已应用，唯一缺失为1789800100000和1789800200000；服务器内受限备份/home/goauto/backups/20260918-305/database.sql（目录0700、文件0600），不下载生产数据。执行后53版本齐全，purchase_task.pdd_order_amount_cent为nullable BIGINT，独立三表和单例租约行已建立，历史回填队列0条。
• 启动对账已登记新POST接口及purchaser权限，管理员沿用原授权；已登录采购列表返回orderWriteback，空批次请求返回422且不入队。未执行真实订单回填或付款，不将空队列健康验证宣称为SYB端到端验收。
• 保持sys_job原启停值不变（任务1/2为1，3/4/5为2），没有更改Cron或主动触发同步。发布前采集/采购运行数均0。
• 原20260916目录的static/var与20260914目录互相循环，不能继续通过旧current间接链接。新release分别直接引用已确认真实存在的/home/goauto/releases/20260907-29ba16e-236/static和/home/goauto/releases/20260903-2d6d244-r1/var；不删除或改写历史资源，不修改其他站点Nginx配置。后续清理旧release前必须检查这些被引用的数据目录。
• 公网入口http://185.216.248.75:9527首页和10项JS/CSS资源HTTP200，/api/v1/health HTTP200；未认证采购接口业务码401。二进制SHA256=4833d779843f0613455ea2b56cadff6efd88d2b96c13e00cb4423cac02e72cb7；发布后结构日志检查无panic/fatal/1146/1054。
• 回滚代码目标保留/home/goauto/releases/20260916-03647dd，追加数据库表/列保留；该旧目录原有static/var循环是已知问题，回退不能宣称资源链自动恢复。不要删除新队列记录或恢复旧数据覆盖后续业务；停止服务亦不保证已发送远端请求取消。

Chrome 订单回填扩展交付与运行（#316）

• 扩展以 chrome-extension/manifest.json 为入口，不随 Server 自动部署。解压安装、授予 Admin Origin、创建或修改客户端密钥授权、真实 PDD 遍历及订单回填都必须按目标环境另行授权；发布 Server 不等于安装或启用扩展。
• 管理员为密钥显式勾选“采购管理 → 回填（writeback）”。建议 HTTPS；若使用项目既有客户端密钥 HTTP 例外，密钥和订单事实会明文传输，风险边界不扩大到 Cookie、JWT 或 Device Token。
• popup 关闭不停止运行；重新打开可查看持久状态。设置在运行时只读。停止会保留已确认批次并阻止后续请求；重启或超时仅以原批次 UUID 重放未确认批次。
• 排错只查看阶段、已读、可提交、已写入、冲突、未完整扫描原因、脱敏错误码和批次状态；不得记录客户端密钥、地址全文、订单号、Cookie、原始 HTML 或真实订单载荷。没有明确列表末尾证据时只能报告未完整扫描。

采购手机准备清单（#331）

采购员配置或更换采购用 Android 手机时逐项确认：

1. 拼多多 App 已登录；
2. 微信已登录；
3. 拼多多已设置默认收货地址；
4. 拼多多默认支付方式为微信支付；
5. GoAuto Agent 已启动，无障碍服务已开启，Admin 设备列表显示在线并已归属对应采购员账号。

任一项不满足时采购会明确失败并提示缺失项（如“未找到支付入口：请确认 PDD 默认支付方式为微信支付”）；Agent 不代为登录、切换支付方式或填写地址。安装新版 Agent 后需手动启动一次 App，心跳恢复后设备才显示在线。