weichen/Agent-System-Dev
1
0
Fork 0
Code Issues 1 Pull Requests 6 Actions 2 Packages Projects Releases Wiki Activity
Files
aecaa52e6bca27c072cd89b295a75c8a4ea744aa
Agent-System-Dev/docs/svc.md
T
weichen ac8db54ecb Add svc.sh update command: auto-detect repo advances and refresh services 
Why:
After the repository moves forward, updating a running service meant
manually figuring out the new commit, rebuilding and redeploying by hand;
the user asked for the tool to detect and update automatically.

Evidence:
- "update [name...] [--check] [--all] [--no-fetch]": fetches origin,
  compares each service's registered source against the latest (Dev repo
  origin/main for local@/dev@ sources, newest Releases version for
  release@), prints a per-service table (current / latest / state), and
  without --check refreshes outdated running services by reusing the full
  deploy pipeline (stop → build/verify → start → health check; persisted
  exec= config and tags survive; update events appended to history).
- local@ services: auto git pull --ff-only origin main + make sync before
  rebuilding, guarded three ways (current branch == main, clean worktree,
  ff-only) — dirty trees or non-main branches are skipped with a warning,
  never touching uncommitted work.
- dev@ sources go straight to the remote main commit via an isolated
  worktree; release@ sources deploy the newest Releases version with
  sha256 verification; postgres and static --dir services are reported as
  not applicable; sources that diverged from or lead the remote are never
  force-updated.
- Verified end to end with five test services: dev@73b2802 → dev@ffda6d3
  (real isolated build, HTTP 200, tag/port preserved, worktree recycled),
  non-main-branch skip, stopped-service warning vs --all, release
  sha256-verified update, --check read-only (svc.env checksums unchanged),
  unregistered name exits 2.
- Fixed en route: a latent bug from the v2 refactor — materialize_dev_commit
  leaked submodule/make stdout into the captured worktree path, breaking
  every real dev@sha deploy since (cp: File name too long); build output
  now goes to stderr. Also fixed an unbound-variable crash in the update
  loop (local statement self-reference under set -u).

Impact:
New read-mostly operational command; no behavior change to existing
commands except dev@sha deploys now actually working end to end.
Makefile gains svc-update; --help and docs/svc.md document the command.

Refs: .task/feature-svc-auto-update.md（任务卡=PR 描述）
2026-09-30 15:22:33 +00:00

625 lines
28 KiB
Markdown
Raw Blame History

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.
# svc.sh 使用说明
`scripts/svc.sh` 是本仓的**本机服务管理器**：把 后端（agent）、前端静态服务（static）、
PostgreSQL 数据库（postgres）三类服务统一为"服务"模型——按提交/版本部署、生命周期管理、
配置分层持久化、标签、事件追溯，以及一套完整的数据库运维能力（换端口 / 备份 / 恢复 /
克隆 / 跨实例搬库）。
设计原则（也是安全边界，详见 [§11 安全与边界](#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. [前提条件](#1-前提条件)
2. [90 秒上手](#2-90-秒上手)
3. [概念与目录布局](#3-概念与目录布局)
4. [命令参考：服务级](#4-命令参考服务级)
5. [命令参考：部署来源](#5-命令参考部署来源)
6. [命令参考：全局命令](#6-命令参考全局命令)
7. [命令参考：数据库](#7-命令参考数据库)
8. [数据库运维手册](#8-数据库运维手册)
9. [配置系统](#9-配置系统)
10. [登记文件与事件流](#10-登记文件与事件流)
11. [安全与边界](#11-安全与边界)
12. [退出码](#12-退出码)
13. [故障排查](#13-故障排查)
14. [配方索引](#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 秒上手
```bash
# 一套演示后端（构建当前工作区 → 启动 → 健康检查）
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](#5-命令参考部署来源)；启动参数组装见 [§9 配置系统](#9-配置系统)；
健康后按 `--model-*` / `--light-*` / `--tavily-keys` 播种（幂等，设置存在 agent 数据目录）。
**static**：
```bash
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
```bash
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（变更登记）
```bash
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（注销）
```bash
scripts/svc.sh rm <name> # 停止 + 移除登记（svc.env/svc.pid）；目录数据历史保留
scripts/svc.sh rm <name> --purge # 连 runtime/<name>/ 整个目录一起删除（含备份！）
```
只管理本脚本登记过的服务；未登记名字会明确报错。
## 5. 命令参考：部署来源
`deploy --from` 支持三种来源（缺省 `local`），agent 与 static 共用：
### 5.1 local —— 当前工作区
```
--from local
```
在主检出跑 `make build`（agent）或 `make frontend`（static），产物复制到服务目录。
**这是唯一会写主检出的路径**，写的都是 gitignore 目录（`bin/`、`node_modules/`、
`modules/frontend/dist/`），不产生任何 git 状态变化。适合"把我现在的工作区跑起来"。
### 5.2 dev@\<sha\> —— Dev 仓提交
```
--from dev # 当前 HEAD
--from dev@<sha> # 指定提交（短/长 sha 均可）
```
流程：`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]`；
- 只列本地已有对象；远端新提交先 `git -C <仓库> fetch`；
- 需要 npm/go 网络（构建在 worktree 内进行）；
- worktree 回收失败会提示手动命令，不阻塞部署结果。
### 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 辅助
```bash
scripts/svc.sh commits [dev|release] [N] # 可部署提交表（默认 20 条）
scripts/svc.sh <name> deploy --pick # 交互式编号选择
scripts/svc.sh <name> deploy --dry-run # 只打印计划
```
`commits` 表格：dev 源标注 `[HEAD]` 与 `[已部署:<服务名>]`（从各服务 `svc.env source=`
汇总）；release 源额外给出版本号与对应 Dev 提交。
## 6. 命令参考：全局命令
### 6.1 list / status（总览）
```bash
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（事件追溯）
```bash
scripts/svc.sh history [name] [N] # 默认全部服务、最近 20 条；首参为纯数字时视为条数
```
合并各服务 `history.jsonl`（按时间排序），字段：时间 / 服务 / kind / 事件 / 结果 /
来源 / pid / 详情。事件类型见 §10.2。
### 6.3 update（自动检索并更新）
```bash
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>` | 当前分支为 main 且工作树干净时：自动 `git pull --ff-only origin main` + `make sync` + 重建；**树脏或非 main 分支则跳过并警告**（绝不碰未提交现场） |
| `dev@<sha>` | `deploy --from dev@<远端 main 最新>`（隔离 worktree 构建，不碰主检出） |
| `release@<版本>` | `deploy --from release@<Releases 最新版本>`（sha256 校验） |
任一服务失败不中断其余服务；最终汇总 `成功/失败/跳过`。退出码：0 全部成功或最新；
1 有失败；2 用法错误。
### 6.4 help
```bash
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（创建实例）
```bash
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
```bash
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 备份
```bash
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 恢复
```bash
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 克隆实例（绑新端口）
```bash
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 跨实例搬库
```bash
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。
```bash
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_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/`；不改主检出 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 |
| `Dev 仓无此提交` | 本地无该对象：`git -C <仓库> fetch` 后重试 |
| `worktree 回收失败` | 按提示手动 `git worktree remove --force runtime/.worktrees/<sha>` |
| `子模块物化失败` | 子模块对象缺失：先 fetch；或网络问题重试 |
| `目标库已有 N 张表——拒绝覆盖` | 确认后加 `--force`（会 drop 重建） |
| `update 报"当前分支非 main"或"工作树不干净" | local 源服务的自动 pull 被防护跳过：先自行收尾/pull，再重跑 update；或改用 `deploy --from dev@<sha>` |
| `list 里服务显示未运行但进程在` | 手工起的进程不满足 pidcheck 标记：脚本不会动它；纳入管理请走 svc 部署 |
## 14. 配方索引
```bash
# ① 演示后端
scripts/svc.sh dev deploy --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 仓）。命令行为以实现为准；发现文档与
实现不一致时，以任务卡记录的方式提出修正。*
Reference in New Issue View Git Blame Copy Permalink