vent_agent_2.0/release

Linux 发布说明

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

工具速查

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

操作	命令
打包	.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" 为例：

~/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。上传新包及校验文件，在它们所在目录执行：

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

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

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

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

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

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

~/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 中的账户和目录改为实际值：

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

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

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 的开发机执行：

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。