# Linux 发布说明

**本地运行、Debug、打包和首次部署的完整步骤见 [项目 README](../README.md)。** 本页补充发布工具、目录、升级和托管操作。

## 工具速查

构建命令在源码根目录执行；安装命令在解压目录执行：

| 操作 | 命令 |
|---|---|
| 打包 | `.venv/bin/python -B release/build.py --version 2.0.0` |
| 校验解压内容 | `python3.12 -B release/verify.py` |
| 安装版本 | `bash release/install.sh --prefix "$HOME/vent-agent"` |
| 首次切换 | `bash release/service.sh activate 2.0.0 --prefix "$HOME/vent-agent"` |
| 后台启动 | `~/vent-agent/current/release/service.sh start` |
| 前台运行 | `~/vent-agent/current/release/service.sh run` |
| 停止 / 状态 / 日志 | `~/vent-agent/current/release/service.sh stop` / `status` / `logs` |

`start` 默认等待健康检查 90 秒，可通过 `--timeout 120` 调整。`status` 在停止或不健康时返回非零；`stop` 超时不会强制杀进程。重启使用 `stop` 再 `start`，没有 `restart` 子命令。

同一部署目录只允许一个实例。统一通过发布脚本或 systemd 启动，避免绕过实例锁直接运行 `main.py`。

## 目录与配置

以 `--prefix "$HOME/vent-agent"` 为例：

```text
~/vent-agent/
├── current  -> releases/2.0.1
├── previous -> releases/2.0.0
├── releases/
│   ├── 2.0.0/                 # 旧版保留
│   └── 2.0.1/                 # 新版源码、文档和独立 .venv
└── shared/
    ├── .env                   # 自动生成，权限 0600；升级不覆盖
    ├── data/                  # SQLite、checkpoint、按用户/会话隔离的文件
    ├── workspace/
    ├── conversation_history/
    ├── large_tool_results/
    ├── logs/server.log        # 后台运行日志
    └── run/                   # 实例锁和 PID 状态
```

每个版本的 `.env` 和运行数据目录都链接到 `shared/`。程序自动读取这份配置，修改后需重启。使用相对 `data/` 路径可让数据库保存在共享目录；自定义绝对路径需要另行备份。

新版本安装时先创建独立虚拟环境、安装哈希锁定的依赖，再用临时数据库自检，不触碰线上数据库；失败清理本次新增目录。安装成功后也不会自动切换或启动。

## 升级与回退

以下演示从 `2.0.0` 升级到 `2.0.1`。上传新包及校验文件，在它们所在目录执行：

```bash
sha256sum -c vent-agent-2.0.1-linux.tar.gz.sha256
tar -xzf vent-agent-2.0.1-linux.tar.gz
cd vent-agent-2.0.1-linux
bash release/install.sh --prefix "$HOME/vent-agent"
~/vent-agent/current/release/service.sh stop
```

停服后备份共享数据，备份文件可能包含密钥，应限制访问：

```bash
(umask 077; tar -czf "$HOME/vent-agent-backup-$(date +%Y%m%d-%H%M%S).tar.gz" \
  -C "$HOME/vent-agent" shared)
```

此命令覆盖共享目录内的 SQLite 和用户文件；**MySQL、自定义绝对路径的数据需另行备份**。确认新旧数据结构兼容后切换：

```bash
~/vent-agent/current/release/service.sh activate 2.0.1
~/vent-agent/current/release/service.sh start
~/vent-agent/current/release/service.sh status
```

仅在旧代码兼容当前数据时回退：

```bash
~/vent-agent/current/release/service.sh stop
~/vent-agent/current/release/service.sh activate 2.0.0
~/vent-agent/current/release/service.sh start
~/vent-agent/current/release/service.sh status
```

**兼容性边界：** 目前没有数据库版本迁移、checkpoint 兼容检查或自动备份。启动时的 `CREATE TABLE IF NOT EXISTS` 不会为已有表补改字段。回退只改变代码和依赖，不恢复旧数据；从备份恢复会丢失备份后的写入。

systemd 托管时，上面的启停改用 `systemctl stop/start vent-agent`；先停服务再备份和 activate，避免自动重启干扰切换。

## systemd 托管

先完成安装、配置和 activate，并停止手动启动的服务。将 [vent-agent.service.example](vent-agent.service.example) 中的账户和目录改为实际值：

- `User`、`Group`：运行服务的账户，需能访问安装目录和共享数据。
- `WorkingDirectory`、`ExecStart`：替换模板中的 `/opt/vent-agent`。

将修改后的文件保存到 `/etc/systemd/system/vent-agent.service`，执行：

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now vent-agent
sudo systemctl status vent-agent
sudo journalctl -u vent-agent -f
```

此后统一使用 `systemctl start/stop/restart vent-agent`；日志在 journal。`service.sh status` 仍可检查健康状态。

## 打包与依赖维护

- `VERSION`：默认发布版本；`--version` 仅修改包内版本。同版本产物和安装目录均不覆盖。
- `release-manifest.json`：包内文件哈希、版本、构建时间、Git 信息和检查结果；源码被修改后，activate / start 会拒绝校验。
- 打包当前工作区，包含未提交修改；白名单排除 `.env`、运行数据、日志和虚拟环境。新增资源类型时同步调整 `build.py` 的白名单。
- 默认执行离线 pytest 和自检；`--skip-checks` 仅供打包排查，会标记检查跳过，**不是服务 Debug 模式**。
- 包中不带 Python 和依赖 wheel；服务器需要 Python 3.12 和下载依赖的网络。

`requirements.txt` 定义依赖范围，`baseline.constraints` 保存已验证版本，`requirements.lock` 固定版本及哈希。更新前两者后，在装有 uv 的开发机执行：

```bash
python3.12 -B release/lock.py
.venv/bin/python -m pip install --require-hashes --only-binary=:all: -r release/requirements.lock
.venv/bin/python -B release/build.py --version 2.0.1
```

构建检查锁文件是否过期、开发环境版本是否一致。服务器安装无需 uv。