Agent-System-Dev/docs/svc.md

svc.sh 使用说明

scripts/svc.sh 是本仓的本机服务管理器：把 后端（agent）、前端静态服务（static）、 PostgreSQL 数据库（postgres）三类服务统一为"服务"模型——按提交/版本部署、生命周期管理、 配置分层持久化、标签、事件追溯，以及一套完整的数据库运维能力（换端口 / 备份 / 恢复 / 克隆 / 跨实例搬库）。

设计原则（也是安全边界，详见 §11 安全与边界）：

• 服务自包含：每个服务的产物、数据、日志、登记都在 runtime/<name>/ 一个目录里， 服务之间互不串版本；删目录 = 完全移除。
• 登记持久化：所有状态落盘（svc.env 当前态 + history.jsonl 事件流），list / history 全部从文件重建，脚本无内存状态、跨会话可追溯。
• 不碰现场：不改主检出 git 状态；只停"自己 pidfile + cmdline 双校验"通过的进程； 端口冲突报错不抢；除 --from local 外的构建全部在隔离 worktree（物化自独立部署 源仓，与当前工作区状态无关——脏树、任意分支均可部署/更新）。

分主题速查：scripts/svc.sh help [model|deploy|lifecycle|db|dbops|config|examples|safety]； 本文档与 --help 内容同源，以实现为准。

---

目录

1. 前提条件
2. 90 秒上手
3. 概念与目录布局
4. 命令参考：服务级
5. 命令参考：部署来源
6. 命令参考：全局命令
7. 命令参考：数据库
8. 数据库运维手册
9. 配置系统
10. 登记文件与事件流
11. 安全与边界
12. 退出码
13. 故障排查
14. 配方索引

---

1. 前提条件

依赖	用途	必需性
bash ≥ 4、git	脚本本体与提交物化	必需
curl	健康检查、设置播种	必需
python3	static 服务（http.server）、播种 payload	static/播种需要
ss	端口占用检测（iproute2）	建议（缺失时跳过检测）
PostgreSQL 工具链（initdb/pg_ctl/psql/pg_dump/pg_restore/pg_isready）	数据库功能	数据库功能需要

PostgreSQL 工具链定位顺序：SVC_PG_BIN 环境变量 → pg_config --bindir → /usr/lib/postgresql/*/bin 等常见路径。都没有时 agent/static 功能不受影响。

2. 90 秒上手

# 一套演示后端（缺省部署远端 main 最新：独立部署源仓物化构建 → 启动 → 健康检查；
# 与当前工作区状态无关。要构建当前工作区：--from local）
scripts/svc.sh dev deploy --mock

# 一个数据库 + 让后端连上它
scripts/svc.sh db create pg1 --port 8890          # initdb，只登记不启动
scripts/svc.sh pg1 start                          # pg_ctl 启动 + 自动建库 + pg_isready
scripts/svc.sh prod deploy --from dev@<sha> \
    --dsn "$(scripts/svc.sh db dsn pg1 --reveal)" # DSN 直接组合进部署

# 日常操作
scripts/svc.sh list                               # 全服务总览
scripts/svc.sh pg1 restart                        # 重启（复用上次配置）
scripts/svc.sh prod logs 100                      # 跟日志
scripts/svc.sh history                            # 事件追溯

# 备份 / 恢复 / 克隆
scripts/svc.sh db backup pg1                      # pg_dump -Fc，自动自检
scripts/svc.sh db restore pg1 --file <dump> --force   # 覆盖恢复需 --force
scripts/svc.sh db clone pg1 pg1test --port 8896   # 克隆一套到新端口

# 把服务刷到远端最新（不依赖当前工作区状态：主检出脏树、任意分支均可）
scripts/svc.sh update --check                     # 先看哪些服务落后
scripts/svc.sh update                             # 自动更新过时且运行中的服务

3. 概念与目录布局

3.1 服务名

^[a-z][a-z0-9-]{0,15}$（小写字母开头，可含数字与连字符，≤16 位）。保留字不可用作 服务名：status list add set db rm create dsn commits history update deploy stop start restart logs help version。

三个名字有默认端口：dev = 127.0.0.1:8788，prod = 127.0.0.1:8787；其余名字按 名称哈希在 8800–9099 确定性派生端口，与已登记端口或正在监听的端口冲突时自动向后 扫描；SVC_<NAME>_ADDR 可显式覆盖。

3.2 目录布局

每个服务自包含于一个目录（--purge 删目录即完全移除）：

runtime/<name>/
├── bin/agent-system    agent 产物（deploy 复制就位；start 只跑这份）
├── htdocs/             static 前端产物（--dir 模式登记外部目录，不复制）
├── data/               agent 数据（SQLite 与工件；--data 可改）
├── pgdata/             postgres 数据（initdb 产物，700）
├── plugins/            agent 插件（随 deploy 复制）
├── backups/            pg_dump 备份（目录 700，文件 600）
├── svc.pid             pidfile
├── svc.log | pg.log    日志（postgres 用 pg.log）
├── svc.env             登记 + 持久化配置（dotenv，600）——见 §10
└── history.jsonl       事件流（append-only JSON Lines）——见 §10

因为产物在环境目录内，start/restart 不依赖主检出；旧版脚本部署过的环境没有环境 产物，升级后首次需重新 deploy 一次（脚本会明确提示）。

3.3 三类服务（kind）

kind	产物	数据	生命周期实现
agent	单二进制（内嵌前端）	data/（SQLite）或外部 DSN	nohup + TERM→KILL
static	htdocs/	无	python3 http.server
postgres	系统工具链	pgdata/	pg_ctl（fast stop，绝不 KILL）

登记里没有 kind= 的旧条目自动视为 agent。同名服务不能换类型，需先 rm。

4. 命令参考：服务级

以下 <name> 均指服务名；action 可省略的只有 deploy。

4.1 deploy（部署并启动）

scripts/svc.sh <name> deploy [--kind agent|static] [--from 源] [--tag T]... [参数...]

流程：解析来源 →（dry-run 则只打印计划）→ 停旧实例 → 物化/构建/校验 → 产物复制到 runtime/<name>/ → 启动 → 健康等待（agent 20s / static 10s）→ 播种设置（agent）→ 登记。任何一步失败都会写 deploy fail 事件并保留现场。

agent：来源见 §5；启动参数组装见 §9 配置系统； 健康后按 --model-* / --light-* / --tavily-keys 播种（幂等，设置存在 agent 数据目录）。

static：

scripts/svc.sh ui deploy --kind static --from dev@<sha>   # 构建该提交的 frontend dist → htdocs/
scripts/svc.sh ui deploy --kind static --dir ../dist      # 直接服务既有目录（不构建不复制）

• --dir 模式登记原始路径（source=dir@<路径>），目录内容由你自己管理；
• release 源对 static 无意义（制品内嵌前端），明确拒绝。

通用参数：

参数	说明
--tag T	标签，可重复；登记合并去重，list --tag 过滤
--addr host:port / --host H / --port P	监听地址
--data DIR	agent 数据目录（默认 runtime/<name>/data）
--plugins DIR	agent 插件源（默认随 deploy 复制环境目录的 plugins/）
--dsn DSN / --auth on|off|auto / --mock	agent 运行参数（非 dev 环境默认 --auth auto）
--model-base/--model-key/--model-name、--light-*、--tavily-keys	启动健康后播种
--dry-run	只解析并打印部署计划（来源、物化路径、产物去向、启动参数）
--pick [dev|release]	交互式编号选提交（需 TTY）
--config FILE / --env FILE	配置文件（见 §9）
-- <剩余参数>	原样透传给 agent-system serve

4.2 start / stop / restart / logs / status

scripts/svc.sh <name> start      # 已在运行则提示并返回 0
scripts/svc.sh <name> stop       # agent/static: TERM→10s→KILL；postgres: pg_ctl -m fast
scripts/svc.sh <name> restart    # stop + start
scripts/svc.sh <name> logs [N]   # tail -f，从最近 N 行起（默认 50）
scripts/svc.sh <name> status     # 单服务详情

• 裸 restart 复用上次启动配置（svc.env exec=），换过端口/参数不用重敲；
• 显式给任何运行参数（或 --config 文件、SVC_* 变量）时整体重建参数；
• agent/static 换端口：restart --port N（进程与登记同步更新）；
• postgres 换端口：set --apply（见 §7.4）或 restart --port N 同样有效。

status 输出示例（postgres）：

  [pg1] postgres  运行中  pid=3115294
    地址 127.0.0.1:8890  数据 /…/runtime/pg1/pgdata
    来源 postgres@local  版本 18.6
    标签 core,local
    库 app  用户 agent
    DSN postgresql://agent:***@127.0.0.1:8890/app（db dsn pg1 --reveal 看密码）

4.3 set（变更登记）

scripts/svc.sh set <name> --tag T...                    # 三类服务通用：改标签（不动进程）
scripts/svc.sh set <pg名> --port N [--host H]           # 未运行：直接改登记
scripts/svc.sh set <pg名> --port N --apply              # 运行中：停止 → 改登记 → 重启
scripts/svc.sh set <pg名> --host 0.0.0.0 --apply        # 换绑定主机同理

• 运行中的 postgres 必须 --apply，否则拒绝（防止登记地址与实际监听不一致）；
• 新端口先做双重校验：未被其他服务登记占用、且当前无人监听；
• --apply 的重启走 pg_ctl 优雅停机，数据安全；
• agent/static 的地址变更用 restart --port N（set 只改登记，会提示）。

4.4 rm（注销）

scripts/svc.sh rm <name>           # 停止 + 移除登记（svc.env/svc.pid）；目录数据历史保留
scripts/svc.sh rm <name> --purge   # 连 runtime/<name>/ 整个目录一起删除（含备份！）

只管理本脚本登记过的服务；未登记名字会明确报错。

5. 命令参考：部署来源

deploy --from 支持三种来源（缺省 = dev 远端最新），agent 与 static 共用：

5.1 dev（缺省）—— 远端最新 / 指定提交

scripts/svc.sh <name> deploy        # 缺省 = dev 远端最新（origin/main）
--from dev                          # 同缺省
--from dev@<sha>                    # 指定提交（短/长 sha 均可）

部署源来自独立部署源仓：脚本自有的干净克隆，默认 ~/.cache/agent-system-svc/src （SVC_SRC_DIR 覆盖；首次使用自动从本仓 origin 克隆，可随时删除、下次自动重建）。 dev 源的提交解析、commits 列举与构建 worktree 物化全部基于它——更新与部署因此 不依赖当前工作区状态：主检出脏树、任意分支、甚至未 fetch 都不影响。

流程：源仓自动 fetch → git worktree add --detach runtime/.worktrees/<sha> <sha> → 递归 git submodule update --init --recursive（子模块精确落位该提交的 gitlink 组合）→ make build/make frontend → 产物复制 → worktree 回收。全程不触碰当前工作区。

• 可用提交列表：scripts/svc.sh commits dev [N]（列源仓 origin/main，自动确保+fetch）；
• 需要 npm/go 网络（构建在 worktree 内进行）；
• worktree 回收失败会提示手动命令，不阻塞部署结果。

5.2 local —— 当前工作区（显式）

--from local

在主检出跑 make build（agent）或 make frontend（static），产物复制到服务目录。 这是唯一会写主检出的路径，写的都是 gitignore 目录（bin/、node_modules/、 modules/frontend/dist/），不产生任何 git 状态变化；也是唯一依赖当前工作区状态 的来源。适合"把我现在的工作区跑起来"。

5.3 release@<版本> —— Releases 仓制品

--from release            # Releases 仓最新（HEAD）
--from release@0.1.0      # 指定版本号
--from release@43ac28d    # 指定 Releases 仓提交也可

制品取 <Releases>/build/<v>/agent-system（+ plugins/），sha256 对 versions/<v>/manifest.json 校验，不符即拒绝部署；并回显该版本对应的 Dev 提交。 仓库定位：SVC_RELEASES_DIR > ../Agent-System-Releases。制品缺失时提示先在 Releases 仓跑 scripts/build-release.sh <v>。

5.4 辅助

scripts/svc.sh commits [dev|release] [N]   # 可部署提交表（默认 20 条）
scripts/svc.sh <name> deploy --pick        # 交互式编号选择
scripts/svc.sh <name> deploy --dry-run     # 只打印计划

commits 表格：dev 源标注 [最新]（源仓 origin/main 顶）与 [已部署:<服务名>] （从各服务 svc.env source= 汇总）；release 源额外给出版本号与对应 Dev 提交。

6. 命令参考：全局命令

6.1 list / status（总览）

scripts/svc.sh list [--tag T]     # status 等价

扫描 runtime/*/svc.env 枚举全部已登记服务：

  NAME         KIND      STATE   PID      ADDR                 SOURCE                   TAGS
  pg1          postgres  运行中  3115294  127.0.0.1:8890       postgres@local           core,local
  prod         agent     运行中  3117059  127.0.0.1:8791       release@0.1.0            stable
  ui-qa        static    未运行 -        127.0.0.1:9054       dir@/tmp/static-demo     ui

STATE 的判定：pidfile 存在且 /proc/<pid>/cmdline 匹配登记的 pidcheck 标记 （agent=二进制路径、postgres=pgdata 路径、static=--directory <目录>）。进程被人手动 杀掉后 STATE 自动落回"未运行"，不会误报。

6.2 history（事件追溯）

scripts/svc.sh history [name] [N]   # 默认全部服务、最近 20 条；首参为纯数字时视为条数

合并各服务 history.jsonl（按时间排序），字段：时间 / 服务 / kind / 事件 / 结果 / 来源 / pid / 详情。事件类型见 §10.2。

6.3 update（自动检索并更新）

scripts/svc.sh update [name...] [--check] [--all] [--no-fetch]

把服务刷到远端最新：fetch 独立部署源仓 → 逐服务比较登记来源与最新 → 报告并（可选） 更新。全程不依赖当前工作区状态（主检出脏树、任意分支均可更新）。

用法	行为
update --check	只输出检测表，不改任何状态
update	自动更新所有"过时且运行中"的服务
update dev pg1	点名更新（已停止的过时服务也会更新并启动）
update --all	范围扩大到已停止服务
update --no-fetch	跳过网络 fetch，用本地已有引用比较（报告注明）

检测表输出：服务 / 当前来源 / 最新 / 状态。状态含义：

• ✓ 最新——登记来源与最新一致，不动作；
• 可更新——本地来源是远端最新的祖先，将被更新；
• 领先远端 main（不动作） / 与远端 main 分叉（不自动更新） / 提交不在远端（不自动更新）——不盲目降级或强更；
• 不适用——postgres（无代码版本）与 static --dir（外部目录）不参与。

各来源的更新动作（复用 deploy 全链路：停旧 → 构建/校验 → 启动 → 健康检查；持久化配置 与标签保留；写 update 事件入 history）：

来源	更新方式
local@<sha> / dev@<sha>	一律 deploy --from dev@<远端 main 最新>（独立部署源仓 + 隔离 worktree 构建；不 pull 主检出、不看工作树状态）
release@<版本>	deploy --from release@<Releases 最新版本>（sha256 校验）

任一服务失败不中断其余服务；最终汇总 成功/失败/跳过。退出码：0 全部成功或最新； 1 有失败；2 用法错误。

6.4 help

scripts/svc.sh            # 一屏速览（短帮助）
scripts/svc.sh -h         # 同上
scripts/svc.sh --help     # 完整帮助（全部命令/参数/约束）
scripts/svc.sh help       # 分主题清单
scripts/svc.sh help <主题> # 主题详解：model deploy lifecycle db dbops config examples safety

7. 命令参考：数据库

7.1 db create（创建实例）

scripts/svc.sh db create pg1 [--port 8890] [--host 127.0.0.1] \
    [--user agent] [--password <pw>] [--db app] \
    [--auth-mode scram-sha-256|md5] [--tag T]...

• initdb 到 runtime/pg1/pgdata（目录 700；密码经 pwfile 传递，即用即删）；
• 默认用户 agent、默认库 agent、认证 scram-sha-256（pg_hba 全线）；
• --password 缺省时自动生成（18 字节十六进制随机）；
• 只登记不启动——scripts/svc.sh pg1 start 启动；端口占用预检在 create 时已做。

7.2 start / stop / restart

• start：pg_ctl -w -t 30 -l pg.log -o "-p <port> -k <环境目录> -c listen_addresses=…" ——socket 目录指向环境目录（不落 pgdata，克隆时不随数据目录传播）； 首次启动自动创建登记库（已存在则跳过）；就绪判定 pg_isready；
• stop：pg_ctl -m fast（回滚事务、断连接、优雅退出）；失败退 SIGTERM； SIGKILL 永远不用于 postmaster；
• restart：stop + start。

7.3 db dsn / db ls

scripts/svc.sh db dsn pg1                 # postgresql://agent:***@127.0.0.1:8890/agent（掩码）
scripts/svc.sh db dsn pg1 --reveal        # 显示真实密码
scripts/svc.sh db dsn pg1 --db other      # 指定库名
scripts/svc.sh db ls pg1                  # 实例内数据库列表（须运行中）

DSN 走 stdout（提示走 stderr），可直接组合：--dsn "$(scripts/svc.sh db dsn pg1 --reveal)"。

7.4 换端口 / 换主机

见 §4.3 set。要点：运行中必须 --apply；登记、DSN、pg_ctl 启动参数联动更新； 数据不动。换端口 = 同机内"迁移"。

8. 数据库运维手册

8.1 备份

scripts/svc.sh db backup pg1                    # 备份登记库
scripts/svc.sh db backup pg1 --db app           # 指定库
scripts/svc.sh db backup pg1 --out /tmp/x.dump  # 自定义输出路径
scripts/svc.sh db backups pg1                   # 列表（时间 / 大小 / 文件名）

• 实现：pg_dump -Fc 走 TCP（实例须运行中），默认落到 runtime/pg1/backups/<UTC时间戳>-<库>.dump；
• 完成后 pg_restore --list 自检归档有效性，失败即删除该文件并记 backup fail；
• 备份只增不删；随 rm --purge 一并删除。

8.2 恢复

scripts/svc.sh db restore pg1 --file <dump>                 # 恢复到登记库
scripts/svc.sh db restore pg1 --file <dump> --db app2       # 恢复到指定库
scripts/svc.sh db restore pg1 --file <dump> --db app --force # 覆盖非空库

目标语义：

目标库状态	行为
不存在	建库 → 恢复
存在且无用户表	直接恢复
存在且有用户表	拒绝；--force 才 DROP DATABASE … WITH (FORCE) → 重建 → 恢复

恢复前先校验文件是合法 pg_dump 归档；完成后回显恢复出的表数；全程事件入 history。 这是脚本里唯一可能删除数据的操作，必须显式 --force 解锁。

8.3 克隆实例（绑新端口）

scripts/svc.sh db clone pg1 pg1test --port 8896                 # 物理克隆（默认）
scripts/svc.sh db clone pg1 pg1test --password newpw --tag test # 换密码/加标签
scripts/svc.sh db clone pg1 pg1test --online                    # 在线克隆（不停源）

物理克隆（默认）：源在运行则短暂 pg_ctl -m fast 停止（一致性要求）→ cp -a pgdata（剔除 postmaster.pid / postmaster.opts；socket 本就不在 pgdata）→ 登记目标（端口 = --port 或派生；用户/库/认证继承，密码可 --password 覆盖；标签 继承 + --tag 追加；source=clone@<源名>）→ 自动复启源。目标不自动启动——按需 scripts/svc.sh pg1test start。

--online：不停源，把源的登记库 dump/restore 到目标——要求目标已 db create + start。适合源不能停的场景。

8.4 跨实例搬库

scripts/svc.sh db copy pgdev pgprod --db app            # pgdev.app → pgprod.app
scripts/svc.sh db copy pgdev pgprod --db app --force    # 目标非空时覆盖

• 双方实例都须运行中（走 TCP dump/restore）；
• --db X 同时命名源库与目标库；缺省取源的登记库；
• 目标库非空须 --force（语义同 restore）；成功后两侧 history 各记一条 copy。

8.5 端口规划建议

• 默认派生区 8800–9099 按服务名哈希，天然分散；多实例并存时建议显式 --port 分配 并记入标签（如 --tag port-8896）；
• 换端口用 set --apply；克隆用 --port 指定；两者都会做占用双重校验。

9. 配置系统

9.1 优先级

命令行参数
  > --config FILE（--env FILE 别名）
    > svc.env 持久化（addr=、exec=）
      > SVC_<NAME>_* 环境变量（.svc.env 自动加载，同层）
        > 默认值

9.2 配置文件

dotenv 格式：KEY=VALUE，支持 # 注释、成对引号、export 前缀；只识别合法变量名， 不 source 执行文件内容（防注入）。建议 .env.dev / .env.prod 等加入 gitignore。

scripts/svc.sh prod deploy --config .env.prod
scripts/svc.sh prod deploy --env .env.prod      # 等价

9.3 环境变量

变量	说明
SVC_<NAME>_ADDR/DATA/DSN/AUTH/MOCK	按服务覆盖（NAME 大写、-→_，如 staging → SVC_STAGING_ADDR）
SVC_RELEASES_DIR	Releases 仓路径（默认 ../Agent-System-Releases）
SVC_SRC_DIR	独立部署源仓路径（默认 ~/.cache/agent-system-svc/src）
SVC_PG_BIN	PostgreSQL 工具链 bindir
SVC_MODEL_BASE/KEY/NAME	主模型（播种 settings.models.chat）
SVC_LIGHT_BASE/KEY/NAME	轻量模型
SVC_TAVILY_KEYS	Tavily 密钥池（逗号分隔）

9.4 持久化语义

• deploy/start 成功后把当前态写入 svc.env（600）：addr、exec（agent 上次 完整启动参数）等；
• 裸 start/restart 复用 exec=；任何显式参数（CLI、--config、SVC_*）出现即 整体重建启动参数；
• 标签合并去重、跨重启保留；postgres 的用户/密码/库名/认证模式持久化，重启不丢。

10. 登记文件与事件流

10.1 svc.env 字段

键	说明
kind	agent / static / postgres（缺省视为 agent）
env	服务名
pid	最近启动 pid
addr	监听地址（持久化，下次 start 复用）
tags	标签（逗号分隔）
source	部署来源：local@<sha> / dev@<sha> / release@<版本> / dir@<路径> / postgres@local / clone@<名>
version	产物版本串（agent-system version 输出）
started	最近启动时间
pidcheck	进程判定标记（见 §6.1）
exec	agent 上次完整启动参数
user / password / dbname / authmode / pgdata	postgres 专属
htdocs	static 专属

10.2 history.jsonl 事件

一行一个 JSON：ts / event / env / kind / source / result / pid / addr / detail。

event	result	触发
create	ok	db create / 物理克隆登记
deploy	begin / ok / fail	agent/static 部署全程
start	ok / fail / warn	启动（fail 含"进程即退/健康检查超时"；warn 为进程起但探活未过）
stop	ok / fail	停止（含 pg_ctl fast / SIGTERM 兜底说明）
set	ok	登记变更（addr 旧 → 新）
backup	ok / fail	备份（文件、大小）
restore	ok / fail	恢复（库、文件、表数）
clone	ok / fail	克隆（物理/在线）
copy	ok / fail	搬库
update	begin / ok / fail	自动更新（from → to）
rm	ok	注销（是否 purge）

11. 安全与边界

• 写入边界：只写 runtime/<name>/、runtime/.worktrees/ 与独立部署源仓 （SVC_SRC_DIR，默认 ~/.cache/agent-system-svc/src，可随时删除重建）；不改主检出 git 状态；--from local 是唯一写主检出构建产物的路径（均 gitignore 目录），也是 唯一依赖当前工作区状态的来源；rm --purge 只删已登记服务的 runtime/<name>/。
• 进程边界：只停"pidfile + cmdline 标记"双校验通过的进程；postgres 走 pg_ctl -m fast，失败退 SIGTERM，SIGKILL 不用于 postmaster；agent/static TERM 10s 后才 KILL。
• 端口边界：被他人占用报错不抢；显式端口双重校验（登记 + 监听）；派生端口避让。
• 秘密与数据：svc.env（含 DB 密码）与备份 600；环境/数据目录 700；DSN 默认掩码； dotenv 不执行文件内容；restore/copy 覆盖非空库必须显式 --force；备份/克隆只增不删。
• 兼容承诺：kind= 缺省视为 agent；旧格式 svc.env（仅 addr/data）在 list/ status 正常显示；旧产物二进制不识别的 --dsn/--auth 自动省略并提示。

12. 退出码

码	含义
0	成功（含"已在运行，无需操作"）
1	运行失败（构建失败、启动失败、校验不过、拒绝覆盖等）
2	用法错误（未知参数/服务名/来源、缺参数、服务未登记等）

13. 故障排查

症状	处置
端口被占用（非本服务）	按提示的占用者处理，或换端口（--port / set --port --apply）
进程启动后即退出	scripts/svc.sh <name> logs 200 / postgres 看 runtime/<name>/pg.log；history 里有 fail 记录
20s 健康检查未通过	进程活着但未响应：查日志与端口；agent 常见原因是 DSN 指向未启动的库
该产物不支持 --dsn/--auth	提示而非错误：旧版本制品自动省略了不支持的 flag；需要该能力请部署新提交
环境产物缺失	该环境没有部署过（或旧版脚本部署）：先 deploy
pg_ctl start 失败	看 pg.log 常见：端口被占、pgdata 权限（须 700）、postmaster 残留
pidfile 指向的进程已不存在	脚本自动清理 pidfile；直接重新 start 即可
sha256 校验失败	制品与 manifest 不符：不要部署；在 Releases 仓重新 build
部署源仓无此提交	源仓已自动 fetch 仍无此对象：确认 sha 正确（scripts/svc.sh commits dev）
worktree 回收失败	按提示手动 git -C <部署源仓> worktree remove --force runtime/.worktrees/<sha>
子模块物化失败	网络或子模块对象问题：重试（部署源仓会自动 fetch）；或检查 git 远端可达性
目标库已有 N 张表——拒绝覆盖	确认后加 --force（会 drop 重建）
提交不在远端（不自动更新）	该服务部署自未推送的本地提交（如 --from local）：重新 deploy（缺省即远端最新）即可纳入更新轨道
list 里服务显示未运行但进程在	手工起的进程不满足 pidcheck 标记：脚本不会动它；纳入管理请走 svc 部署

14. 配方索引

# ① 演示后端（缺省部署远端 main 最新；--from local 构建当前工作区）
scripts/svc.sh dev deploy --mock
scripts/svc.sh dev deploy --from local --mock

# ② 建库 + 后端连库
scripts/svc.sh db create pg1 --port 8890
scripts/svc.sh pg1 start
scripts/svc.sh prod deploy --from dev@<sha> --dsn "$(scripts/svc.sh db dsn pg1 --reveal)"

# ③ 按提交部署 + 回退
scripts/svc.sh commits dev
scripts/svc.sh v1 deploy --from dev@73b2802 --tag test
scripts/svc.sh v1 deploy --from release@0.1.0

# ④ 双版本并行对比
scripts/svc.sh a deploy --from dev@<shaA> --port 8801
scripts/svc.sh b deploy --from dev@<shaB> --port 8802

# ⑤ 前端静态服务
scripts/svc.sh ui deploy --kind static --from dev@<sha>
scripts/svc.sh ui2 deploy --kind static --dir ../frontend/dist

# ⑥ 备份 → 改坏 → 恢复
scripts/svc.sh db backup pg1
scripts/svc.sh db restore pg1 --file runtime/pg1/backups/<最新>.dump --force

# ⑦ 克隆隔离环境
scripts/svc.sh db clone pg1 pg1test --port 8896
scripts/svc.sh pg1test start
scripts/svc.sh qa deploy --from dev@<sha> --dsn "$(scripts/svc.sh db dsn pg1test --reveal)"

# ⑧ 开发库搬到 prod 实例
scripts/svc.sh db copy pgdev pgprod --db app --force

# ⑨ 换端口
scripts/svc.sh set pg1 --port 8895 --apply

# ⑩ 把服务刷到远端最新（主检出脏树/任意分支均可）
scripts/svc.sh update --check        # 看哪些落后
scripts/svc.sh update                # 更新过时且运行中的（数据与配置保留）
scripts/svc.sh update dev            # 只刷新指定服务

# ⑪ 总览与追溯
scripts/svc.sh list --tag test
scripts/svc.sh history pg1 50

---

本文档对应 scripts/svc.sh（Agent-System-Dev 仓）。命令行为以实现为准；发现文档与 实现不一致时，以任务卡记录的方式提出修正。