25

Deployment-and-Operations

ila edited this page 2026-09-27 11:40:40 +08:00

Table of Contents

• 部署与运维
• 当前线上拓扑
• Agent HTTP 例外
• 发布与验证
• API 长请求超时约束
• 回滚
• 蝦皮规格自动匹配任务运维（#195）
• SYB 异常规格 AI 定时任务（#198）
• 定时任务执行历史运维（#199）
• 客户端密钥部署与验证（#237）
• Windows 本机运行目录与 #237 迁移验证（2026-09-07）
• 蝦皮详情匹配等待与回读（#254）
• 本地 Supervisor 与局域网访问
• SYB 订单号回填 worker 部署与排错（#305）
• #305/#306 线上发布验证（2026-09-18）
• Chrome 订单回填扩展交付与运行（#316）
• 采购手机准备清单（#331）
• #341 售后角色与账号迁移
• #338 退货匹配发布

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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

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，心跳恢复后设备才显示在线。

#341 售后角色与账号迁移

• 发布前需单独授权执行 server/cmd/migrate/migration/version-local/1789801100000_after_sales_role.go。迁移会创建/维护 after_sales 角色、复制采购员当前菜单/API 授权，并创建四个售后账号；不会重置已存在账号密码。
• 首次创建账号时仅在当前迁移进程设置 GOAUTO_AFTER_SALES_INITIAL_PASSWORD，执行完成后立即清除；不得把密码写入仓库、日志、工单或 Wiki。
• 本地和线上均执行迁移后回读角色、四个账号的角色绑定、退货接口策略及幂等结果，再按常规流程重启 GoAuto API。

#338 退货匹配发布

发布时执行退货匹配及售后权限迁移，切换 Server/Web release，重启 goauto.service 并 reload Nginx；发布后验证健康接口、Web 首页、售后登录及退货匹配只读接口，不用真实商品提交作为健康检查。