合入编排完善第 2 波(集成):应用库可移植到 PostgreSQL(nr8/a)、第 1 波与下一轮遗留收口(nr8/l)、多进程协调(nr8/b)、部署时 PostgreSQL 一起起(nr8/d)

This commit is contained in:
ThearchyHelios
2026-10-19 15:45:16 +08:00
250 changed files with 16961 additions and 1086 deletions
+191 -6
View File
@@ -10,6 +10,7 @@
| 文件 | 用途 |
| --- | --- |
| `image.tar` | Docker 镜像(`docker save` 导出),镜像名 `agentlab:__AGENTLAB_VERSION__` |
| `postgres-image.tar` | 内置 PostgreSQL 的镜像(`install --postgres` 时用,见「用 PostgreSQL」)。包因此多约 160 MB,导入后在 docker 里占约 0.7 GB;只用 SQLite 或外接 PostgreSQL 时用不上,打包时用 `--no-postgres` 就没有这个文件 |
| `deploy.sh` | 一键部署脚本:安装、启动、停止、升级、卸载 |
| `agentlab.env` | 配置:端口、监听地址、数据目录、模型 Key、代理、沙箱 |
| `README.md` | 本说明 |
@@ -21,7 +22,8 @@
- **架构要一致**:这个包是 `linux/__AGENTLAB_ARCH__`。在目标机上运行 `uname -m`:
`aarch64` 对应 arm64(ARM 单板机要装 64 位系统),`x86_64` 对应 amd64。不一致的镜像跑不起来,
deploy.sh 会在导入前就报出来;
- 磁盘:镜像导入后约 0.8~1 GB(看 Docker 用的存储方式),另留数据目录的空间;
- 磁盘:镜像导入后约 0.8~1 GB(看 Docker 用的存储方式),另留数据目录的空间;用内置 PostgreSQL 再加约 0.7 GB 的镜像
和库本身的空间(在 docker 的数据卷里);
- 可选:宿主机支持 KVM(有 `/dev/kvm`)时,代码会在 microVM 里执行,隔离最强,见下面的「代码沙箱」;
- 当前用户能用 docker(在 `docker` 组里),或者用 `sudo` 运行 deploy.sh。
@@ -41,6 +43,7 @@ nano agentlab.env
deploy.sh 依次:检查 docker 和架构 → 导入镜像(`docker load -i image.tar`,本机已有就跳过)→
创建数据目录 → 启动容器(`--restart unless-stopped`,开机自动起来)→ 等健康检查通过 → 打印访问地址。
库缺省是数据目录里的 SQLite;要用 PostgreSQL 的新部署把第 3 步换成 `./deploy.sh install --postgres`(见「用 PostgreSQL」)。
## 访问
@@ -58,7 +61,26 @@ deploy.sh 依次:检查 docker 和架构 → 导入镜像(`docker load -i im
所有数据都在 `DATA_DIR`(默认是包目录下的 `data/`):数据库 `agentlab.db`、执行断点 `checkpoints.db`、
工件、上传文件、沙箱工作区,以及加密密钥 `.secret_key`。**要备份的就是这个目录**,
丢了 `.secret_key`,存进去的 API Key 就解不开了。
丢了 `.secret_key`,存进去的 API Key 就解不开了。目录里的 `.agentlab-data` 是服务启动时建的标记,deploy.sh 改属主前按它
(或 `agentlab.db`、`.secret_key`、`.postgres/state`)认出这是 AgentLab 的数据目录,别删。数据库放在 PostgreSQL 时(下面「用 PostgreSQL」)没有这两个库文件,
另用 `pg_dump` 备份数据库。
`./deploy.sh upgrade` 换版本之前会自动备份一次库:SQLite 拷到数据目录的 `backups/sqlite/<时间>/`(SQLite 的备份接口,
一致的一份),内置 PostgreSQL 用 `pg_dump` 存到 `backups/postgres/`,各只留最近 5 份(`agentlab.env` 里 `BACKUP_KEEP=` 改)。
备份里是整个库(含加密存着的密钥),所以 `backups/` 和下面每一层目录都是 0700、备份文件 0600,属主同数据目录(uid 10001):
宿主机上要看、要拷走都得用 sudo(`sudo ls -l data/backups/sqlite/`、`sudo cp -a data/backups /别处/`)。
这只是升级的保险,不代替下面的整目录备份:工件、上传文件和 `.secret_key` 不在里面。
用 SQLite 的部署要从 `backups/sqlite/` 恢复(以缺省的 `./data` 为例,`<时间>` 换成目录名):
```bash
./deploy.sh stop
sudo rm -f data/agentlab.db-wal data/agentlab.db-shm data/checkpoints.db-wal data/checkpoints.db-shm
sudo cp -p data/backups/sqlite/<时间>/agentlab.db data/backups/sqlite/<时间>/checkpoints.db data/ # -p:属主仍是 10001
./deploy.sh start
```
`-wal`、`-shm` 要先删:留着的话 SQLite 会把它们当成换回来的库的一部分。
deploy.sh 会把数据目录的属主改成容器里的用户(uid 10001),所以备份、删除要用 sudo。
停下来备份最稳妥(以默认的 `./data` 为例,在包目录里执行):
@@ -71,6 +93,162 @@ sudo tar -czf ../agentlab-data-$(date +%Y%m%d).tar.gz data
恢复:停掉容器,把备份解回 `DATA_DIR`,再 `./deploy.sh start`。
## 用 PostgreSQL
库有三种放法,选一种:
| | 怎么用 | 库在哪里 | 数据目录里 |
| --- | --- | --- | --- |
| SQLite(缺省) | `./deploy.sh` | 数据目录的 `agentlab.db`、`checkpoints.db` | 全部数据 |
| 内置 PostgreSQL | 新部署 `./deploy.sh install --postgres`;已经在用 SQLite 的 `./deploy.sh migrate-to-postgres` | docker 数据卷 `<CONTAINER_NAME>-pgdata` | 工件、上传文件、`.secret_key`、库的密码 `.postgres/` 和备份 `backups/` |
| 外接 PostgreSQL | `agentlab.env` 里设 `AGENTLAB_DATABASE_URL` | 你自己的 PostgreSQL | 工件、上传文件、`.secret_key` |
内置和外接只能选一种:`agentlab.env` 里设了 `AGENTLAB_DATABASE_URL`(或 `AGENTLAB_CHECKPOINT_URL`)又加 `--postgres`,
或者数据目录已经是内置的,deploy.sh 照实报错、不起任何容器。不管哪种,数据目录都照样要挂、要备份。
### 内置 PostgreSQL
`./deploy.sh install --postgres` 在 AgentLab 旁边再起一个 PostgreSQL 容器:
- 镜像缺省 `postgres:16.15`(小版本固定在 deploy.sh 里,每台机器起的都一样;离线包里带着 `postgres-image.tar`,本机已有同名镜像
就不导入)。要换在 `agentlab.env` 里写 `POSTGRES_IMAGE=postgres:16.x`,再 `./deploy.sh install`:服务先停、库的容器按新镜像重建,
数据卷不动;新镜像起不来(跨大版本时数据格式不通用)就换回原来的镜像、照实报错。
- 两个容器在同一个 docker 网络 `<CONTAINER_NAME>-net` 里,PostgreSQL 的端口**不对外开**,只有 AgentLab 的容器连得到。
- 库的数据在 docker 数据卷 `<CONTAINER_NAME>-pgdata` 里(不在数据目录:数据目录会被改属主,PostgreSQL 的文件属主不能动)。
- 密码第一次部署时自动生成,存在数据目录的 `.postgres/password` 和 `.postgres/pgpass`(都是 0600),不进镜像、不进日志、
不进 `docker inspect`,`agentlab.env` 里什么都不用填。AgentLab 的容器按 `PGPASSFILE` 读它。**丢了数据目录就连不上这个库**,
所以数据目录照样要整份备份。
- 用过一次之后这个数据目录就一直是内置 PostgreSQL(记在 `.postgres/state`),之后的 `install`、`upgrade`、`start` 不用再加
`--postgres`。
- `start` 先起库、等 `pg_isready` 通过再起服务;`stop` 先停服务再停库。`restart` 缺省只重启服务(库停着的话先把库起来),
`restart --postgres` 连库一起重启(先停服务再停库,再先起库后起服务)。开机时两个容器一起被 docker 拉起来,库还没就绪时
服务按退避重试(日志里写着「应用库还没就绪……秒后重试」),最多等 90 秒(`AGENTLAB_DB_STARTUP_TIMEOUT`),不会一上来就崩。
- 表结构和默认数据(内置模板、技能)每次启动自动补齐;几个工作进程(`AGENTLAB_WORKERS`)同时起也只做一次(库里的锁)。
- `./deploy.sh status` 显示两个容器的状态,`./deploy.sh logs --postgres` 看库的日志。
可以在 `agentlab.env` 里改的(都有缺省值,一般不用写):
| 项 | 缺省 | 说明 |
| --- | --- | --- |
| `POSTGRES_IMAGE` | `postgres:16.15` | 库的镜像 |
| `POSTGRES_CONTAINER` | `<CONTAINER_NAME>-postgres` | 库的容器名 |
| `DOCKER_NETWORK` | `<CONTAINER_NAME>-net` | 两个容器共用的网络 |
| `POSTGRES_VOLUME` | `<CONTAINER_NAME>-pgdata` | 库的数据卷 |
| `BACKUP_KEEP` | `5` | 升级前自动备份留几份(SQLite 也按它) |
环境变量 `DEPLOY_<名字>` 盖过 `agentlab.env` 里的同名项(这几项加上 `HOST_PORT`、`BIND_ADDR`、`DATA_DIR`、`CONTAINER_NAME`),
一台机器上并排部署两套、或者测试时用。
**备份。** `upgrade` 前自动 `pg_dump` 一份到 `backups/postgres/`(0600,见「数据和备份」)。平时要手动备份(服务开着也行,
`pg_dump` 读的是一致的快照;`umask 077` 让导出的文件只有自己读得到):
```bash
(umask 077; docker exec agentlab-postgres pg_dump -U agentlab -d agentlab -Fc > agentlab-$(date +%Y%m%d).dump)
```
再加上数据目录(见「数据和备份」),两样合起来才是完整的一份。
**恢复。** 用 `backups/postgres/` 里的备份把库换回去(以缺省的名字、在包目录里为例,`<备份>` 换成文件名,`sudo ls data/backups/postgres/`
看有哪些)。备份文件是 0600、属主 10001,宿主机上的人读不到,所以最后一步在一个以 10001 运行的临时容器里读它,不用 sudo:
```bash
./deploy.sh stop # 两个都停
docker start agentlab-postgres # 只起库
until docker exec agentlab-postgres pg_isready -q -h 127.0.0.1 -U agentlab; do sleep 1; done
docker exec agentlab-postgres psql -U agentlab -d postgres \
-c 'DROP DATABASE agentlab WITH (FORCE)' -c 'CREATE DATABASE agentlab OWNER agentlab'
docker run --rm --network agentlab-net -v "$(pwd)/data:/data" --user 10001:10001 -e PGPASSFILE=/data/.postgres/pgpass \
--entrypoint pg_restore postgres:16.15 -h agentlab-postgres -U agentlab -d agentlab --no-owner /data/backups/postgres/<备份>
./deploy.sh start
```
自己手动导出、放在别处的备份(上面「备份」那条命令导出的,属主是你自己)直接从宿主机喂进去:
`docker exec -i agentlab-postgres pg_restore -U agentlab -d agentlab --no-owner < agentlab-<日期>.dump`。
数据目录要换回同一时间的备份,工件、上传文件和库里的记录才对得上。
**从 SQLite 切过来。** 正在用 SQLite 的部署运行 `./deploy.sh migrate-to-postgres`,它依次:
1. 停服务;
2. 备份 SQLite 库到 `backups/sqlite/<时间>/`;
3. 起内置 PostgreSQL(第一次生成密码);
4. 用镜像里的 `python -m app.db copy-to-postgres` 先核对(`--dry-run`,只数行数);
5. 正式导入,逐表按主键核对、断点按条数核对(停在审批上的、中断了的运行导过去之后照样能接着跑);
6. 在数据目录里记下「已切到内置 PostgreSQL」,按内置库起服务、等健康检查通过。
记下之前任何一步出错,都停在原地:服务按 SQLite 原样恢复(原来在跑就起回来),库的容器停掉,屏幕上是那一步的原话。
处理好之后重新运行就行,重复执行是安全的:已经切过的什么都不做;上次没切成、留在内置库里的半份数据先清空再导,
不会和 SQLite 上后来改过的混在一起(`status` 里会写「上次 migrate-to-postgres 没切成」)。数据卷已经存在、又不是这个
数据目录上次没切成留下的(比如以前卸载时留下的另一份库),它不会去清空,照实报错让你决定。
切完之后 `agentlab.db`、`checkpoints.db` 原样留在数据目录里、不再使用,`backups/sqlite/` 里还有一份。**什么时候能删**:
在 PostgreSQL 上用一段时间、做过一次完整备份(`pg_dump` 加数据目录)之后。删之前它们是回退的路:`./deploy.sh stop`、
`sudo rm <数据目录>/.postgres/state`、`./deploy.sh install`,就回到切换那一刻的 SQLite(切换之后在 PostgreSQL 上新产生的东西
不会带回来;库的容器停着不用,`docker rm -f agentlab-postgres` 可删)。
**首次在 Linux 上切换前的检查。** 第一次在一台机器上 `install --postgres` 或 `migrate-to-postgres` 之前,花几分钟看一遍
(以缺省的 `./data` 为例,在包目录里执行):
- **docker 版本**:`docker version --format '{{.Server.Version}}'`,要 20.10 以上(健康检查、自建网络、`--stop-timeout` 都要用);
运行 deploy.sh 的用户在 `docker` 组里(`id -nG` 里有 docker),否则整条命令前加 sudo。
- **属主**:`ls -lnd data` 第三列应是 `10001`(deploy.sh 改的)。数据目录不要放在 NFS、SMB 这类不认 uid 的挂载上:属主改不过去,
服务写不进去。
- **权限**:切换(或第一次起库)之后看一眼——`ls -ld data/.postgres` 应是 `drwx--x--x`(0711),`cat data/.postgres/state`
不用 sudo 就能读到(deploy.sh 在宿主机上直接读它,读不到时会退回去用容器读,只是慢一点);`sudo ls -ln data/.postgres`
里 `password`、`pgpass` 是 `-rw-------`、属主 10001;`sudo ls -ld data/backups` 是 `drwx------`。
- **磁盘空间**:切换时数据目录里要放得下两份库(`backups/sqlite/` 里的一份备份,加上导入时的临时快照,用完就删),
另外 docker 的存储目录要放得下 PostgreSQL 的镜像(约 0.7 GB)和库本身(大致和 SQLite 的库一样大,索引多的表会大一些)。
看大小:`sudo du -sh data/agentlab.db data/checkpoints.db`;看剩余:`df -h data` 和
`df -h "$(docker info --format '{{.DockerRootDir}}')"`。
- **整目录备份**:切换会先自动备份一份库,但还是建议先按「数据和备份」停服务整份打包一次数据目录。切换期间服务是停着的,
时长大致是导入的时间(每秒几千到几万行,看机器)。
**卸载。** `./deploy.sh uninstall` 连库的容器和网络一起删,数据卷和数据目录都留着;同一个数据目录再 `./deploy.sh install`
就接着用原来的库。确定不要了:`docker volume rm agentlab-pgdata`(不可恢复)。
### 外接 PostgreSQL
库在你自己的 PostgreSQL 上(要先建好),在 `agentlab.env` 里加一行再 `./deploy.sh install`:
```bash
AGENTLAB_DATABASE_URL=postgresql+asyncpg://agentlab:<密码>@<数据库地址>:5432/agentlab
```
容器里的 `127.0.0.1` 是容器自己:数据库在别的机器上就写那台的地址;就在这台机器上,写宿主机在 docker 网桥上的地址
(一般是 `172.17.0.1`),并让 PostgreSQL 监听这个地址、`pg_hba.conf` 放行容器的网段。执行断点也进同一个库。
表结构和默认数据同样在每次启动时自动补齐,库暂时连不上时同样按退避重试。`agentlab.env` 末尾「外接 PostgreSQL 与多进程(可选)」
一段列着这几项(地址、断点库、PgBouncer、工作进程、连接池、启动时等库),都注释着,要用的去掉行首的 `#`;它们和别的 `AGENTLAB_*`
一样经 `--env-file` 原样进容器。
已经在用 SQLite 的,先把数据导过去(同一个镜像里带着导入命令;`--dry-run` 只核对、不写):
```bash
./deploy.sh stop
sudo tar -czf ../agentlab-data-$(date +%Y%m%d).tar.gz data # 先备份
docker run --rm --user 10001:10001 -v "$(pwd)/data:/data" --env-file agentlab.env --entrypoint python \
agentlab:<版本> -m app.db copy-to-postgres /data --dry-run
docker run --rm --user 10001:10001 -v "$(pwd)/data:/data" --env-file agentlab.env --entrypoint python \
agentlab:<版本> -m app.db copy-to-postgres /data
./deploy.sh install # agentlab.env 里已经有 AGENTLAB_DATABASE_URL
```
导入结束时逐表打印来源和目标的行数、断点的条数,对不上的列出来、退出码非零;重跑只补没有的行,不重复、不覆盖。
导完 `data/agentlab.db` 可以留着当回退:把那一行删掉、重新部署就回到 SQLite(导入之后在 PostgreSQL 上新产生的东西不会回来)。
外接的库 deploy.sh 不备份,自己用 `pg_dump` 备份。
### 多进程
**多进程。** 换成 PostgreSQL 之后可以在容器里起几个工作进程:`agentlab.env` 里加 `AGENTLAB_WORKERS=4`(缺省 1)再
`./deploy.sh upgrade`。几个进程共用一个端口,各自在库里登记、续租约;一个进程没了,别的进程在租约到期后接手它留下的运行、
问数据和后台任务(规矩见仓库 README「多进程」)。SQLite 时设大于 1 会启动失败(照实报错:SQLite 只支持单进程)。
几台机器、几个容器指着同一个库也行,但数据目录要放在共享存储上、每台挂在同一个路径,限制见仓库 README「多进程」。
内置 PostgreSQL 是直连(中间没有 PgBouncer),多进程时什么都不用另设(不用 `AGENTLAB_DATABASE_DIRECT_URL`;设了它、或者
`AGENTLAB_DB_PGBOUNCER=1`,deploy.sh 照实拦下)。库还是 SQLite 时 `AGENTLAB_WORKERS` 大于 1,deploy.sh 在起容器之前就拦下。新旧版本的进程不能同时
连着一个库(代码里拦着:新版本发现库里还有活着的旧版本进程就拒绝启动)。`./deploy.sh upgrade` 就是按这个顺序做的:先停掉旧容器
(里面的全部工作进程一起停)、备份,再起新版本;旧进程要是被强杀、登记还没过期,新版本启动时会等它过期(最多半分钟左右)。
同一个库还接着别处的 AgentLab 进程(另一台机器、另一个容器)的,升级前先把它们也停掉。
## 升级
把新版本的离线包拷到机器上,解到一个新目录,然后:
@@ -83,7 +261,9 @@ cp ../agentlab-<旧版本>-linux-__AGENTLAB_ARCH__/agentlab.env . # 沿用原
```
`upgrade` 导入新镜像、用新镜像替换容器,数据目录不动。deploy.sh 会检查新配置指向的数据目录和
正在用的是不是同一个,不是就停下来提醒,不会让新版本悄悄从一个空库开始。
正在用的是不是同一个,不是就停下来提醒,不会让新版本悄悄从一个空库开始。换之前先停旧服务、自动备份一次库
(见「数据和备份」),备份没做成就把旧服务起回来、不升级。新版本启动时自动补表结构和默认数据,不用手动迁移。
用内置 PostgreSQL 的,新包里的 `POSTGRES_IMAGE` 换了小版本时库的容器跟着换(数据卷不动)。
新容器没通过健康检查时,原来的容器会保留为 `agentlab-previous`,屏幕上会打印回退命令。
旧镜像也留着,确认新版本没问题后可以 `docker rmi agentlab:<旧版本>` 删掉。
@@ -99,6 +279,7 @@ cp ../agentlab-<旧版本>-linux-__AGENTLAB_ARCH__/agentlab.env . # 沿用原
./deploy.sh logs # 最后 200 行
./deploy.sh logs -f # 持续跟随,Ctrl-C 退出
./deploy.sh logs --tail 1000
./deploy.sh logs --postgres # 内置 PostgreSQL 的日志
```
日志由 docker 自动轮转(单个 10 MB、保留 3 个),不会塞满存储卡。
@@ -108,12 +289,16 @@ cp ../agentlab-<旧版本>-linux-__AGENTLAB_ARCH__/agentlab.env . # 沿用原
```bash
./deploy.sh stop # 停止(开机也不会自动起来)
./deploy.sh start # 再启动
./deploy.sh restart # 重启
./deploy.sh restart # 重启服务(内置 PostgreSQL 不跟着重启)
./deploy.sh restart --postgres # 连内置 PostgreSQL 一起重启
./deploy.sh uninstall # 删除容器,保留数据和镜像
./deploy.sh uninstall --purge-image # 连镜像一起删
./deploy.sh uninstall --purge-image # 连镜像一起删(PostgreSQL 的镜像不删,别的东西可能也在用)
```
卸载**永远不删数据**。确定不要了再手动删除数据目录(不可恢复):`sudo rm -rf <数据目录>`。
内置 PostgreSQL 时这几个命令按顺序管两个容器(起的时候先起库,停的时候先停服务;`restart` 不加 `--postgres` 只动服务),
卸载连库的容器和网络一起删。
卸载**永远不删数据**。确定不要了再手动删除数据目录(不可恢复):`sudo rm -rf <数据目录>`;内置 PostgreSQL 的数据卷另删:
`docker volume rm <CONTAINER_NAME>-pgdata`。
改了 `agentlab.env` 之后运行 `./deploy.sh install` 让新配置生效(`restart` 不会重读配置)。
+43
View File
@@ -111,3 +111,46 @@ ENABLE_MICROVM=auto
# sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0
# 这一步会放宽整台机器的限制,自行权衡。
ENABLE_BWRAP=0
# ---- 内置 PostgreSQL(可选)----
# 缺省库是数据目录里的 SQLite。新部署要用内置的 PostgreSQL 运行 ./deploy.sh install --postgres,已经在用 SQLite 的运行
# ./deploy.sh migrate-to-postgres(见 README.md「用 PostgreSQL」)。密码自动生成在数据目录的 .postgres/ 里,这里不用填。
# 和外接 PostgreSQL(AGENTLAB_DATABASE_URL)只能选一种。下面几项是给 deploy.sh 用的,都有缺省值,一般不用改;要改去掉
# 行首的 # 再 ./deploy.sh install。
#
# 库的镜像(小版本固定;离线包里带着同一个标签的 postgres-image.tar)
# POSTGRES_IMAGE=postgres:16.15
# 库的容器名,缺省 <CONTAINER_NAME>-postgres
# POSTGRES_CONTAINER=agentlab-postgres
# 两个容器共用的 docker 网络,缺省 <CONTAINER_NAME>-net(库的端口不对外,只在这个网络里可见)
# DOCKER_NETWORK=agentlab-net
# 库的数据放在这个 docker 数据卷里,缺省 <CONTAINER_NAME>-pgdata(卸载不删)
# POSTGRES_VOLUME=agentlab-pgdata
# upgrade 前自动备份库(SQLite 拷到 backups/sqlite/,内置 PostgreSQL 用 pg_dump 存到 backups/postgres/),只留最近几份
# BACKUP_KEEP=5
# ---- 外接 PostgreSQL 与多进程(可选)----
# 库放在你自己的 PostgreSQL 上(库要先建好):去掉 AGENTLAB_DATABASE_URL 行首的 # 填好地址,再 ./deploy.sh install。
# 和上面的内置 PostgreSQL 只能选一种:两个都用时 deploy.sh 照实报错、不起容器。容器里的 127.0.0.1 是容器自己:库就在这台机器上时
# 写宿主机在 docker 网桥上的地址(一般是 172.17.0.1),并让 PostgreSQL 监听这个地址、pg_hba.conf 放行容器的网段(一般是
# 172.17.0.0/16);库在别的机器上就写那台的地址。下面这些 AGENTLAB_* 都原样传进容器(docker run --env-file 这个文件)
# AGENTLAB_DATABASE_URL=postgresql+asyncpg://agentlab:密码@172.17.0.1:5432/agentlab
# 断点放另一个库时才设(不设就和应用库同一个库)
# AGENTLAB_CHECKPOINT_URL=postgresql://agentlab:密码@172.17.0.1:5432/agentlab_checkpoints
# 前面有 PgBouncer 的事务模式时:AGENTLAB_DB_PGBOUNCER 设成 1,并另给直连 PostgreSQL 的地址(会话模式、直连都不用这两项)。
# 内置 PostgreSQL 是直连,设了 deploy.sh 会拦下
# AGENTLAB_DB_PGBOUNCER=0
# AGENTLAB_DATABASE_DIRECT_URL=postgresql+asyncpg://agentlab:密码@172.17.0.1:5432/agentlab
# 容器里起几个工作进程,缺省 1。只有用 PostgreSQL(内置或外接)时才能大于 1:SQLite 时 deploy.sh 先拦下
# AGENTLAB_WORKERS=1
# 工作进程在库里的租约多长、隔多久续一次(秒,缺省 30、5)。租约到期没续上算进程没了,别的进程接手它的活
# AGENTLAB_WORKER_LEASE_S=30
# AGENTLAB_WORKER_HEARTBEAT_S=5
# 连接池(每个工作进程一套):常驻几条、高峰再多开几条、等空闲连接最多几秒、一条连接用多久换新(缺省 10、20、30、1800 秒)。
# 进程多了连接数跟着乘,PostgreSQL 的 max_connections 要够(见 README「用 PostgreSQL」的连接数的账)
# AGENTLAB_DB_POOL_SIZE=10
# AGENTLAB_DB_MAX_OVERFLOW=20
# AGENTLAB_DB_POOL_TIMEOUT=30
# AGENTLAB_DB_POOL_RECYCLE=1800
# 启动时库还没就绪最多等几秒(按退避重试,内置、外接都一样),缺省 90
# AGENTLAB_DB_STARTUP_TIMEOUT=90
+588 -36
View File
@@ -11,6 +11,8 @@ IMAGE="agentlab:$VERSION"
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
ENV_FILE="$HERE/agentlab.env"
IMAGE_TAR="$HERE/image.tar"
# 内置 PostgreSQL 的镜像:离线包里带一份(scripts/package-docker.sh 打进去),本机已经有同名镜像就不导入
POSTGRES_IMAGE_TAR="$HERE/postgres-image.tar"
# 给沙箱用 bubblewrap 时容器要加的权限,说明见 agentlab.env 的沙箱一节
BWRAP_OPTS=(--security-opt seccomp=unconfined --security-opt systempaths=unconfined --security-opt apparmor=unconfined)
@@ -19,19 +21,35 @@ usage() {
cat <<USAGE
用法:./deploy.sh [子命令] [选项]
install 部署(默认):导入镜像、创建数据目录、启动容器,等健康检查通过后打印访问地址。
install [--postgres]
部署(默认):导入镜像、创建数据目录、启动容器,等健康检查通过后打印访问地址。
已经有同名容器的,先停掉再换成新的,数据保留。改了 agentlab.env 也用它让配置生效。
本机有 KVM 时会先试着启动一台 microVM,起得来才让代码在 microVM 里执行(见 agentlab.env)。
upgrade 用这个包里的镜像替换正在用的容器,数据保留。旧镜像留着,方便回退。
start | stop | restart
启动 / 停止 / 重启容器。
status 查看容器状态、健康检查、数据目录、代码沙箱和访问地址。
logs [-f] [--tail N]
查看日志(默认最后 200 行),-f 持续跟随。
--postgres:新部署用内置的 PostgreSQL(再起一个 PostgreSQL 容器,同一个 docker 网络、端口不对外;
密码第一次自动生成,存在数据目录的 .postgres/ 里)。用过一次之后这个数据目录就一直是内置
PostgreSQL,之后的 install / upgrade / start 不用再加。已经在用 SQLite 的,用 migrate-to-postgres。
upgrade 用这个包里的镜像替换正在用的容器,数据保留。旧镜像留着,方便回退。换之前先自动备份库
(SQLite:数据目录的 backups/sqlite/;内置 PostgreSQL:pg_dump 到 backups/postgres/;各留最近
BACKUP_KEEP 份,缺省 5)。新版本启动时自动补表结构(迁移)和默认数据。
migrate-to-postgres
把正在用 SQLite 的部署切到内置 PostgreSQL:停服务 → 备份 → 起 PostgreSQL → 先核对再导入 → 记下
「已切换」→ 起服务。哪一步出错都停在原地、仍用 SQLite。重复执行是安全的;SQLite 的库文件原样留着。
start | stop 启动 / 停止。内置 PostgreSQL 时先起库、等它就绪再起服务;停的时候先停服务再停库。
restart [--postgres]
重启服务(库停着的话先把库起来)。--postgres:内置 PostgreSQL 也一起重启(先停服务、再停库,
起的时候先起库)。
status 查看容器状态、健康检查、数据目录、用的哪种库、代码沙箱和访问地址。
logs [-f] [--tail N] [--postgres]
查看日志(默认最后 200 行),-f 持续跟随,--postgres 看内置 PostgreSQL 的。
uninstall [--purge-image]
删除容器。默认保留数据和镜像,--purge-image 连镜像一起删。数据永远不删。
删除容器(内置 PostgreSQL 的容器和网络一起删)。默认保留数据和镜像,--purge-image 连 AgentLab
的镜像一起删。数据永远不删:数据目录和 PostgreSQL 的数据卷都留着。
-h, --help 显示这段说明。
环境变量 DEPLOY_<名字> 盖过 agentlab.env 里的同名项(测试、一台机器上并排部署两套时用):HOST_PORT、BIND_ADDR、
DATA_DIR、CONTAINER_NAME,以及内置 PostgreSQL 的 POSTGRES_IMAGE、POSTGRES_CONTAINER、DOCKER_NETWORK、POSTGRES_VOLUME,
备份份数 BACKUP_KEEP。
这个包:AgentLab ${VERSION}(linux/${IMAGE_ARCH})
USAGE
}
@@ -48,6 +66,9 @@ CMD="install"
FOLLOW=""
TAIL="200"
PURGE_IMAGE=""
WITH_POSTGRES=""
LOGS_POSTGRES=""
RESTART_POSTGRES=""
if [ $# -gt 0 ]; then
case "$1" in
-h|--help) usage; exit 0 ;;
@@ -56,7 +77,7 @@ if [ $# -gt 0 ]; then
esac
fi
case "$CMD" in
install|upgrade|start|stop|restart|status|logs|uninstall) ;;
install|upgrade|migrate-to-postgres|start|stop|restart|status|logs|uninstall) ;;
*) printf '认不出的子命令:%s\n\n' "$CMD" >&2; usage >&2; exit 2 ;;
esac
while [ $# -gt 0 ]; do
@@ -68,6 +89,13 @@ while [ $# -gt 0 ]; do
TAIL="$2"; shift ;;
--tail=*) [ "$CMD" = logs ] || bad_arg "$1"; TAIL="${1#--tail=}" ;;
--purge-image) [ "$CMD" = uninstall ] || bad_arg "$1"; PURGE_IMAGE=1 ;;
--postgres)
case "$CMD" in
install) WITH_POSTGRES=1 ;;
logs) LOGS_POSTGRES=1 ;;
restart) RESTART_POSTGRES=1 ;;
*) bad_arg "$1" ;;
esac ;;
*) bad_arg "$1" ;;
esac
shift
@@ -106,6 +134,23 @@ DATA_DIR="./data"
CONTAINER_NAME="agentlab"
ENABLE_BWRAP="0"
ENABLE_MICROVM="auto"
# 内置 PostgreSQL。小版本固定:同一个包到哪台机器都起同一个版本(pg_dump 和库同版本);要换在 agentlab.env 里写
# POSTGRES_IMAGE。容器、网络、数据卷的名字缺省跟着 CONTAINER_NAME 走
POSTGRES_IMAGE="postgres:16.15"
POSTGRES_CONTAINER=""
DOCKER_NETWORK=""
POSTGRES_VOLUME=""
BACKUP_KEEP="5"
# agentlab.env 里设了外接的库(AGENTLAB_DATABASE_URL 等)没有:只记设了哪一项,值(带密码)不读进来
EXTERNAL_DB=""
EXTERNAL_URL_SET=""
DIRECT_URL_SET=""
# 这两项要看值:PgBouncer 事务模式的开关(内置库是直连,开了就拦下)、工作进程数(SQLite 只能是 1)。都原样经 --env-file 进容器
PGBOUNCER_VALUE=""
WORKERS_VALUE=""
# 内置 PostgreSQL 里的库名、用户名(PostgreSQL 容器第一次初始化时按它建)
PG_DB="agentlab"
PG_USER="agentlab"
read_env() {
[ -f "$ENV_FILE" ] || die "找不到 ${ENV_FILE},它应该和 deploy.sh 在同一个目录"
@@ -120,8 +165,19 @@ read_env() {
key="$(trim "${line%%=*}")"
val="${line#*=}"
case "$key" in
HOST_PORT|BIND_ADDR|DATA_DIR|CONTAINER_NAME|ENABLE_BWRAP|ENABLE_MICROVM)
HOST_PORT|BIND_ADDR|DATA_DIR|CONTAINER_NAME|ENABLE_BWRAP|ENABLE_MICROVM|POSTGRES_IMAGE|POSTGRES_CONTAINER|\
DOCKER_NETWORK|POSTGRES_VOLUME|BACKUP_KEEP)
printf -v "$key" '%s' "$(unquote "$(trim "$val")")" ;;
AGENTLAB_DATABASE_URL|AGENTLAB_CHECKPOINT_URL|AGENTLAB_DATABASE_DIRECT_URL)
if [ -n "$(trim "$val")" ]; then
[ -n "$EXTERNAL_DB" ] || EXTERNAL_DB="$key"
case "$key" in
AGENTLAB_DATABASE_URL) EXTERNAL_URL_SET=1 ;;
AGENTLAB_DATABASE_DIRECT_URL) DIRECT_URL_SET=1 ;;
esac
fi ;;
AGENTLAB_DB_PGBOUNCER) PGBOUNCER_VALUE="$(unquote "$(trim "$val")")" ;;
AGENTLAB_WORKERS) WORKERS_VALUE="$(unquote "$(trim "$val")")" ;;
AGENTLAB_DATA_DIR|AGENTLAB_WEB_DIST|AGENTLAB_PORT|AGENTLAB_HOST)
die "agentlab.env 第 $n 行:不要设 ${key}。容器里的路径和端口是固定的,改宿主机这边用 DATA_DIR、HOST_PORT、BIND_ADDR" ;;
*)
@@ -131,13 +187,30 @@ read_env() {
esac
done < "$ENV_FILE"
# 环境变量 DEPLOY_<名字> 盖过 agentlab.env(测试、并排部署两套时用)
local k v
for k in HOST_PORT BIND_ADDR DATA_DIR CONTAINER_NAME POSTGRES_IMAGE POSTGRES_CONTAINER DOCKER_NETWORK \
POSTGRES_VOLUME BACKUP_KEEP; do
v="$(printenv "DEPLOY_$k" 2>/dev/null || true)"
[ -z "$v" ] || printf -v "$k" '%s' "$v"
done
[ -n "$POSTGRES_CONTAINER" ] || POSTGRES_CONTAINER="$CONTAINER_NAME-postgres"
[ -n "$DOCKER_NETWORK" ] || DOCKER_NETWORK="$CONTAINER_NAME-net"
[ -n "$POSTGRES_VOLUME" ] || POSTGRES_VOLUME="$CONTAINER_NAME-pgdata"
case "$HOST_PORT" in ''|*[!0-9]*) die "HOST_PORT 必须是数字:$HOST_PORT" ;; esac
if [ "$HOST_PORT" -lt 1 ] || [ "$HOST_PORT" -gt 65535 ]; then die "HOST_PORT 超出范围:$HOST_PORT"; fi
[ -n "$BIND_ADDR" ] || die "BIND_ADDR 不能为空(所有网卡写 0.0.0.0,只给本机用写 127.0.0.1)"
[ -n "$DATA_DIR" ] || die "DATA_DIR 不能为空"
case "$CONTAINER_NAME" in
''|[!a-zA-Z0-9]*|*[!a-zA-Z0-9_.-]*) die "CONTAINER_NAME 只能用字母、数字和 _ . -,并以字母或数字开头:$CONTAINER_NAME" ;;
esac
for k in CONTAINER_NAME POSTGRES_CONTAINER DOCKER_NETWORK POSTGRES_VOLUME; do
v="${!k}"
case "$v" in
''|[!a-zA-Z0-9]*|*[!a-zA-Z0-9_.-]*) die "$k 只能用字母、数字和 _ . -,并以字母或数字开头:$v" ;;
esac
done
[ "$POSTGRES_CONTAINER" != "$CONTAINER_NAME" ] || die "POSTGRES_CONTAINER 不能和 CONTAINER_NAME 同名:$CONTAINER_NAME"
case "$BACKUP_KEEP" in ''|*[!0-9]*|0) die "BACKUP_KEEP 要是正整数:$BACKUP_KEEP" ;; esac
case "$POSTGRES_IMAGE" in ''|*[[:space:]]*) die "POSTGRES_IMAGE 写错了:$POSTGRES_IMAGE" ;; esac
case "$ENABLE_BWRAP" in 0|1) ;; *) die "ENABLE_BWRAP 只能是 0 或 1:$ENABLE_BWRAP" ;; esac
case "$ENABLE_MICROVM" in auto|0|1) ;; *) die "ENABLE_MICROVM 只能是 auto、0 或 1:$ENABLE_MICROVM" ;; esac
@@ -192,19 +265,19 @@ image_present() { docker image inspect "$IMAGE" >/dev/null 2>&1; }
verify_tar() {
# 拷贝中途断了、U 盘出错,docker load 的报错不好懂:先对一下校验和
local name="${1:-image.tar}" line
[ -f "$HERE/SHA256SUMS" ] || return 0
command -v sha256sum >/dev/null 2>&1 || return 0
local line
line="$(grep ' image.tar$' "$HERE/SHA256SUMS" || true)"
line="$(grep " $name\$" "$HERE/SHA256SUMS" || true)"
[ -n "$line" ] || return 0
say "校验 image.tar"
say "校验 $name"
(cd "$HERE" && printf '%s\n' "$line" | sha256sum -c --quiet -) \
|| die "image.tar 校验和对不上,文件不完整或损坏。重新拷一份离线包再试"
|| die "$name 校验和对不上,文件不完整或损坏。重新拷一份离线包再试"
}
load_image() {
[ -f "$IMAGE_TAR" ] || die "本地没有镜像 ${IMAGE},包里也找不到 image.tar"
verify_tar
verify_tar image.tar
say "导入镜像:docker load -i image.tar(性能较弱的 ARM 单板机上可能要一两分钟)"
docker load -i "$IMAGE_TAR"
image_present || die "导入后仍找不到 ${IMAGE},image.tar 可能不是这个版本的"
@@ -266,8 +339,12 @@ fix_data_owner() {
owner="$(ls -nd "$DATA_ABS" | awk '{print $3}')"
[ "$owner" = "$uid" ] && return 0
# 改属主前确认这确实是一个新目录或者 AgentLab 的数据目录,免得 DATA_DIR 写错改了别的东西
if [ -n "$(ls -A "$DATA_ABS" 2>/dev/null)" ] && [ ! -e "$DATA_ABS/agentlab.db" ]; then
die "DATA_DIR 指向的 $DATA_ABS 不是空目录,也不像 AgentLab 的数据目录(里面没有 agentlab.db)。
# 认这几样里的一样:agentlab.db(库在 SQLite)、.secret_key(自动生成的加密密钥)、.agentlab-data(服务启动时建的标记,
# 库放在 PostgreSQL、密钥又由 AGENTLAB_SECRET_KEY 给时只有它)、.postgres/state(deploy.sh 记的用哪种库:内置库起来了、
# 服务还没起过时只有它)。只有 uploads/ 这类普通目录名的不认,免得 chown 错了别人的目录
if [ -n "$(ls -A "$DATA_ABS" 2>/dev/null)" ] && [ ! -e "$DATA_ABS/agentlab.db" ] \
&& [ ! -e "$DATA_ABS/.secret_key" ] && [ ! -e "$DATA_ABS/.agentlab-data" ] && [ ! -e "$DATA_ABS/.postgres/state" ]; then
die "DATA_DIR 指向的 $DATA_ABS 不是空目录,也不像 AgentLab 的数据目录(里面没有 agentlab.db、.secret_key、.agentlab-data)。
为免改错别的文件的属主,请指向一个新目录,或者原来的 AgentLab 数据目录"
fi
say "把数据目录的属主改成容器里的用户(uid ${uid}),容器里的服务才写得进去"
@@ -395,12 +472,13 @@ run_container() {
--log-opt max-size=10m --log-opt max-file=3 \
${extra[@]+"${extra[@]}"} \
${MICROVM_OPTS[@]+"${MICROVM_OPTS[@]}"} \
${DB_OPTS[@]+"${DB_OPTS[@]}"} \
"$IMAGE" >/dev/null
}
wait_healthy() {
local name="$1" state health i
say "等健康检查通过"
say "等 $name 通过健康检查"
for i in $(seq 1 90); do
state="$(container_state "$name")"
health="$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{end}}' "$name" 2>/dev/null || true)"
@@ -487,6 +565,271 @@ deploy_container() {
die "容器没通过健康检查。看上面的日志;常见原因见 README 的常见问题"
}
# ---------------------------------------------------------------------------
# 用的哪种库:sqlite(缺省)、builtin(内置 PostgreSQL,数据目录里记着)、external(agentlab.env 里设了
# AGENTLAB_DATABASE_URL)。内置和外接互斥
# ---------------------------------------------------------------------------
PG_STATE_REL=".postgres/state"
# 应用容器里连内置库:不带密码,密码在数据目录的 pgpass 里(PGPASSFILE),不进容器的环境变量、不进日志
PG_PASSFILE="/data/.postgres/pgpass"
MODE="sqlite"
DB_OPTS=()
# 数据目录里记的状态:sqlite、builtin,或者 migrating(migrate-to-postgres 开始往内置库里导了、还没切成,用的仍是
# SQLite)。.postgres/ 是 0711、state 是 0644,一般宿主机上直接读得到;读不到(权限)就交给容器里的 app.ops 读
stored_state() {
local file="$DATA_ABS/$PG_STATE_REL" dir="$DATA_ABS/.postgres" line
if [ -r "$file" ]; then
line="$(grep '^mode=' "$file" 2>/dev/null | head -n 1 || true)"
case "${line#mode=}" in builtin|migrating) echo "${line#mode=}" ;; *) echo sqlite ;; esac
elif [ -e "$file" ] || { [ -e "$dir" ] && [ ! -x "$dir" ]; } || [ ! -x "$DATA_ABS" ]; then
ops state | tail -n 1
else
echo sqlite
fi
}
# 实际用的:只有 builtin 算内置,migrating 还是 SQLite
stored_mode() {
case "$(stored_state)" in builtin) echo builtin ;; *) echo sqlite ;; esac
}
volume_exists() { docker volume inspect "$1" >/dev/null 2>&1; }
resolve_mode() {
local stored
stored="$(stored_mode)"
if [ -n "$EXTERNAL_DB" ]; then
if [ "$stored" = builtin ] || [ -n "$WITH_POSTGRES" ]; then
die "两种库只能选一种:agentlab.env 里设了 ${EXTERNAL_DB}(外接 PostgreSQL),这个数据目录又是内置 PostgreSQL$( \
[ -n "$WITH_POSTGRES" ] && [ "$stored" != builtin ] && printf '(--postgres)')。
- 用内置的:把 agentlab.env 里的 $EXTERNAL_DB 那一行删掉;
- 用外接的:去掉 --postgres;数据目录已经是内置 PostgreSQL 的,先用 pg_dump 把内置库的数据导出来,换一个新的数据目录再部署"
fi
MODE="external"
elif [ "$stored" = builtin ]; then
MODE="builtin"
elif [ -n "$WITH_POSTGRES" ]; then
if [ -e "$DATA_ABS/agentlab.db" ]; then
die "数据目录 $DATA_ABS 里已经有 SQLite 的库(agentlab.db)。install --postgres 只给新部署用;要把现有数据搬进内置
PostgreSQL,运行 ./deploy.sh migrate-to-postgres"
fi
MODE="builtin"
else
MODE="sqlite"
fi
check_db_settings
DB_OPTS=()
if [ "$MODE" = builtin ]; then
DB_OPTS=(--network "$DOCKER_NETWORK"
-e "AGENTLAB_DATABASE_URL=postgresql+asyncpg://$PG_USER@$POSTGRES_CONTAINER:5432/$PG_DB"
-e "PGPASSFILE=$PG_PASSFILE")
fi
}
# agentlab.env 里和库有关的几项是否和用的哪种库对得上(resolve_mode 定了 MODE 之后查;migrate-to-postgres 按切过去的内置库查)
pgbouncer_on() {
case "$(printf '%s' "$PGBOUNCER_VALUE" | tr '[:upper:]' '[:lower:]')" in 1|true|yes|on) return 0 ;; *) return 1 ;; esac
}
check_db_settings() {
local mode="${1:-$MODE}"
if [ -n "$DIRECT_URL_SET" ] && [ -z "$EXTERNAL_URL_SET" ]; then
die "agentlab.env 里设了 AGENTLAB_DATABASE_DIRECT_URL,却没设 AGENTLAB_DATABASE_URL:直连地址是给外接 PostgreSQL 配 PgBouncer 用的,
要和 AGENTLAB_DATABASE_URL 一起设。不用外接的库就把它删掉"
fi
if [ "$mode" = builtin ] && pgbouncer_on; then
die "agentlab.env 里 AGENTLAB_DB_PGBOUNCER=${PGBOUNCER_VALUE},但内置 PostgreSQL 是直连、中间没有 PgBouncer。把这一行删掉或改成 0"
fi
case "$WORKERS_VALUE" in
''|*[!0-9]*) ;;
*)
if [ "$mode" = sqlite ] && [ "$WORKERS_VALUE" -gt 1 ]; then
die "agentlab.env 里 AGENTLAB_WORKERS=${WORKERS_VALUE},但库是 SQLite:SQLite 只支持单进程,服务会拒绝启动。
- 改回 1(或删掉这一行);
- 要多进程,先换成 PostgreSQL:./deploy.sh migrate-to-postgres(内置)或设 AGENTLAB_DATABASE_URL(外接)"
fi ;;
esac
}
mode_label() {
case "$MODE" in
builtin) echo "内置 PostgreSQL(容器 ${POSTGRES_CONTAINER},数据卷 ${POSTGRES_VOLUME})" ;;
external) echo "外接 PostgreSQL(agentlab.env 里的 ${EXTERNAL_DB})" ;;
*) echo "SQLite(数据目录里的 agentlab.db)" ;;
esac
}
# 在一个用完就删的容器里、以容器里的用户跑 python -m app.ops(数据目录归它,宿主机上的人不一定写得进去)。
# start / stop 这类用容器正在用的镜像(这个包的镜像可能已经删了)
OPS_IMAGE=""
ops() {
docker run --rm --network none -v "$DATA_ABS:/data" --entrypoint python "${OPS_IMAGE:-$IMAGE}" -m app.ops "$@"
}
# ---------------------------------------------------------------------------
# 内置 PostgreSQL:镜像、网络、密码、容器、备份
# ---------------------------------------------------------------------------
pg_image_present() { docker image inspect "$POSTGRES_IMAGE" >/dev/null 2>&1; }
ensure_pg_image() {
if pg_image_present; then
return 0
fi
[ -f "$POSTGRES_IMAGE_TAR" ] || die "本地没有 PostgreSQL 的镜像 ${POSTGRES_IMAGE},包里也没有 postgres-image.tar。
- 能联网:docker pull ${POSTGRES_IMAGE}
- 离线:用 scripts/package-docker.sh 重新打包(缺省会带上它),或者在能联网的机器上 docker save 一份拷过来 docker load"
verify_tar postgres-image.tar
say "导入 PostgreSQL 镜像:docker load -i postgres-image.tar"
docker load -i "$POSTGRES_IMAGE_TAR"
pg_image_present || die "导入后仍找不到 ${POSTGRES_IMAGE}:postgres-image.tar 里的不是这个标签。agentlab.env 里的 POSTGRES_IMAGE 要和包里的一致"
}
ensure_network() {
docker network inspect "$DOCKER_NETWORK" >/dev/null 2>&1 && return 0
say "创建 docker 网络 ${DOCKER_NETWORK}(PostgreSQL 只在这个网络里可见,端口不对外)"
docker network create "$DOCKER_NETWORK" >/dev/null
}
pg_secrets() {
# 第一次生成密码(0600),之后沿用;pgpass 按容器名重写。密码只在数据目录里,不打印
ops postgres-secrets --host "$POSTGRES_CONTAINER" --port 5432 --db "$PG_DB" --user "$PG_USER" >/dev/null \
|| die "没能在数据目录里生成 PostgreSQL 的密码文件($DATA_ABS/.postgres/)"
}
check_pg_is_ours() {
local role
role="$(docker inspect -f '{{index .Config.Labels "agentlab.role"}}' "$POSTGRES_CONTAINER" 2>/dev/null || true)"
[ "$role" = postgres ] || die "已经有一个叫 $POSTGRES_CONTAINER 的容器,但它不是 deploy.sh 起的内置 PostgreSQL。
改一下 agentlab.env 里的 POSTGRES_CONTAINER(缺省是 <CONTAINER_NAME>-postgres)"
}
run_pg_container() {
docker run -d \
--name "$POSTGRES_CONTAINER" \
--label agentlab.role=postgres \
--restart unless-stopped \
--network "$DOCKER_NETWORK" \
-e "POSTGRES_USER=$PG_USER" \
-e "POSTGRES_DB=$PG_DB" \
-e POSTGRES_PASSWORD_FILE=/run/agentlab/password \
-v "$POSTGRES_VOLUME:/var/lib/postgresql/data" \
-v "$DATA_ABS/.postgres/password:/run/agentlab/password:ro" \
--health-cmd "pg_isready -h 127.0.0.1 -U $PG_USER -d $PG_DB" \
--health-interval 5s --health-timeout 5s --health-retries 5 --health-start-period 60s \
--stop-timeout 60 \
--log-opt max-size=10m --log-opt max-file=3 \
"$POSTGRES_IMAGE" >/dev/null
}
pg_logs_to_stderr() {
echo >&2; echo "---- PostgreSQL 最后 40 行日志 ----" >&2
docker logs --tail 40 "$POSTGRES_CONTAINER" >&2 2>&1 || true
echo "----" >&2
}
# install / upgrade 时 POSTGRES_IMAGE 和现有容器的不一样(新包换了小版本,或者 agentlab.env 里改了):服务先停,库的容器
# 按新镜像重建,数据卷不动。新镜像起不来(多半是跨了大版本,数据格式不认)就换回原来的镜像,什么都不改
PG_APPLY_IMAGE=""
replace_pg_image() {
local cur="$1" was_running=""
[ "$(container_state "$CONTAINER_NAME")" = running ] && was_running=1
say "内置 PostgreSQL 换镜像:$cur → ${POSTGRES_IMAGE}(数据卷 $POSTGRES_VOLUME 不动)"
stop_app
docker stop "$POSTGRES_CONTAINER" >/dev/null 2>&1 || true
docker rm -f "$POSTGRES_CONTAINER" >/dev/null
if run_pg_container && wait_healthy "$POSTGRES_CONTAINER"; then
return 0
fi
pg_logs_to_stderr
docker rm -f "$POSTGRES_CONTAINER" >/dev/null 2>&1 || true
local wanted="$POSTGRES_IMAGE"
POSTGRES_IMAGE="$cur"
if run_pg_container && wait_healthy "$POSTGRES_CONTAINER"; then
[ -z "$was_running" ] || docker start "$CONTAINER_NAME" >/dev/null 2>&1 || true
die "内置 PostgreSQL 用 $wanted 起不来(见上面的日志;跨大版本时数据格式不通用,要 pg_dump 导出、新版本里导回),
已换回原来的 ${cur},什么都没改。agentlab.env 里的 POSTGRES_IMAGE 改回 $cur 再运行"
fi
die "内置 PostgreSQL 用 $wanted 起不来,换回 $cur 也没起来。看 ./deploy.sh logs --postgres"
}
# 起内置库(没有就建,停着就起),等 pg_isready 通过
start_pg() {
ensure_network
if container_exists "$POSTGRES_CONTAINER"; then
check_pg_is_ours
local cur
cur="$(docker inspect -f '{{.Config.Image}}' "$POSTGRES_CONTAINER")"
if [ -n "$PG_APPLY_IMAGE" ] && [ "$cur" != "$POSTGRES_IMAGE" ]; then
replace_pg_image "$cur"
return 0
fi
if [ "$(container_state "$POSTGRES_CONTAINER")" != running ]; then
say "启动内置 PostgreSQL(${POSTGRES_CONTAINER})"
docker start "$POSTGRES_CONTAINER" >/dev/null || die "内置 PostgreSQL 的容器起不来,见上面 docker 的报错"
fi
else
say "启动内置 PostgreSQL(${POSTGRES_CONTAINER},${POSTGRES_IMAGE},数据卷 ${POSTGRES_VOLUME})"
run_pg_container || die "PostgreSQL 容器启动失败,见上面 docker 的报错"
fi
if ! wait_healthy "$POSTGRES_CONTAINER"; then
pg_logs_to_stderr
die "内置 PostgreSQL 没就绪(pg_isready 不通过)。看上面的日志"
fi
}
stop_pg() {
container_exists "$POSTGRES_CONTAINER" || return 0
[ "$(container_state "$POSTGRES_CONTAINER")" = running ] || return 0
say "停止内置 PostgreSQL(${POSTGRES_CONTAINER},数据保留)"
docker stop "$POSTGRES_CONTAINER" >/dev/null
}
stop_app() {
container_exists "$CONTAINER_NAME" || return 0
[ "$(container_state "$CONTAINER_NAME")" = running ] || return 0
say "停止 ${CONTAINER_NAME}(数据保留)"
docker stop "$CONTAINER_NAME" >/dev/null
}
image_user() { docker image inspect -f '{{.Config.User}}' "$IMAGE"; }
# pg_dump 一份到数据目录的 backups/postgres/,只留最近 BACKUP_KEEP 份。用 PostgreSQL 镜像里的 pg_dump(和库同版本),
# 以数据目录的属主写文件。备份里是整个库:目录 0700(app.ops backup-dir)、文件 0600(umask 077 下建,没有别人读得到的那一刻)
backup_pg() {
local stamp file
stamp="$(date -u +%Y%m%dT%H%M%SZ)"
file="backups/postgres/$PG_DB-$stamp.dump"
say "备份内置 PostgreSQL:pg_dump 到 $DATA_ABS/$file"
ops backup-dir postgres >/dev/null || { warn "没能在数据目录里建备份目录 backups/postgres/"; return 1; }
docker run --rm --network "$DOCKER_NETWORK" -v "$DATA_ABS:/data" --user "$(image_user)" -e "PGPASSFILE=$PG_PASSFILE" \
--entrypoint sh "$POSTGRES_IMAGE" -c 'umask 077 && exec pg_dump "$@"' pg_dump \
-h "$POSTGRES_CONTAINER" -U "$PG_USER" -d "$PG_DB" -Fc -f "/data/$file" \
|| { warn "pg_dump 失败"; return 1; }
ops prune --dir /data/backups/postgres --keep "$BACKUP_KEEP" >/dev/null || warn "旧备份没删掉,不影响这次升级"
}
backup_sqlite() {
local out
say "备份 SQLite 库到 $DATA_ABS/backups/sqlite/"
out="$(ops backup-sqlite --keep "$BACKUP_KEEP")" || { warn "SQLite 库备份失败"; return 1; }
# 容器里看到的是 /data/…,换成宿主机上的路径
case "$out" in
/data/*) say "备份好了:${out/#\/data/$DATA_ABS}" ;;
*) say "$out" ;;
esac
}
backup_before_upgrade() {
case "$MODE" in
builtin) backup_pg ;;
sqlite) backup_sqlite ;;
external) say "外接 PostgreSQL:升级前请自己备份那个库(pg_dump),这里不替你做" ;;
esac
}
# ---------------------------------------------------------------------------
# 子命令
# ---------------------------------------------------------------------------
@@ -498,6 +841,26 @@ cmd_install() {
prepare_data
check_existing
fix_data_owner
resolve_mode
say "应用库:$(mode_label)"
PG_APPLY_IMAGE=1
if [ "$MODE" = builtin ]; then
ensure_pg_image
if [ "$(stored_mode)" != builtin ]; then
# 新部署:数据卷要是已经有了,里面的库是按别的密码初始化的(多半是以前 uninstall 留下的),连不上,也不该拿来用
volume_exists "$POSTGRES_VOLUME" && die "docker 数据卷 $POSTGRES_VOLUME 已经存在,不是这个数据目录建的(多半是以前卸载时留下的
内置 PostgreSQL 的数据)。
- 要接着用那份数据:把 DATA_DIR 指回原来的数据目录再 ./deploy.sh install;
- 确定不要了:docker volume rm ${POSTGRES_VOLUME}(不可恢复),再运行;
- 两份都留着:agentlab.env 里另起一个 POSTGRES_VOLUME 的名字"
pg_secrets
# 先记下再起库:新数据目录里没有 SQLite 的库,没什么可「切」的;起库失败了重来也认得出数据卷是自己的
ops state --set builtin >/dev/null || die "没能在数据目录里记下「用内置 PostgreSQL」"
else
pg_secrets
fi
start_pg
fi
decide_microvm
deploy_container
}
@@ -519,39 +882,190 @@ cmd_upgrade() {
prepare_data
check_existing
fix_data_owner
resolve_mode
say "应用库:$(mode_label)"
PG_APPLY_IMAGE=1
if [ "$MODE" = builtin ]; then
ensure_pg_image
pg_secrets
start_pg
fi
decide_microvm
# 先停旧服务再备份:备份的是升级前最后的样子。备份失败就把旧服务起回来、不升级
stop_app
if ! backup_before_upgrade; then
docker start "$CONTAINER_NAME" >/dev/null 2>&1 || true
die "升级前的备份没做成,没有升级,原来的服务已经起回来了"
fi
# 新版本启动时自动补表结构(迁移)和默认数据,几个工作进程同时起也只做一次
deploy_container
if [ "$old_image" != "$IMAGE" ] && docker image inspect "$old_image" >/dev/null 2>&1; then
echo "旧镜像 $old_image 还留着,方便回退。确认新版本没问题后可以删:docker rmi $old_image"
fi
}
cmd_start() {
check_docker; read_env; require_container
docker start "$CONTAINER_NAME" >/dev/null
# 把正在用 SQLite 的部署切到内置 PostgreSQL。记下「已切换」之前任何一步出错:服务按 SQLite 原样恢复(原来在跑就起回来)、
# 内置库的容器停掉,数据目录里只多了 backups/ 里的一份备份和 .postgres/ 里的密码、状态(migrating)。重复执行:已经切过的
# 什么都不做;上次没切成留在内置库里的半份数据先清空再导,不会和 SQLite 里后来改过的混在一起
MIGRATE_WAS_RUNNING=""
MIGRATE_HAD_APP=""
MIGRATE_DEPLOYING=""
migrate_rollback() {
local prev="$CONTAINER_NAME-previous"
echo >&2
warn "$1"
if [ -n "$MIGRATE_DEPLOYING" ]; then
# 按内置库起的新容器不能留着(它带着 --restart,会一直去连内置库):换回原来的,原来就没有就删掉
if container_exists "$prev"; then
docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
docker rename "$prev" "$CONTAINER_NAME" >/dev/null 2>&1 || warn "没能把原来的容器改回 ${CONTAINER_NAME}:docker rename $prev $CONTAINER_NAME"
elif [ -z "$MIGRATE_HAD_APP" ]; then
docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
fi
# 已经记成 builtin 的改回 migrating:仍用 SQLite,数据卷还认得出是这个数据目录的
ops state --set migrating >/dev/null 2>&1 || warn "没能把数据目录的状态改回去:手动把 $DATA_ABS/$PG_STATE_REL 里的 mode=builtin 改成 mode=migrating"
fi
if container_exists "$CONTAINER_NAME"; then
if [ -n "$MIGRATE_WAS_RUNNING" ]; then
docker start "$CONTAINER_NAME" >/dev/null 2>&1 && say "服务已按 SQLite 起回来" || warn "服务没能起回来:./deploy.sh start"
else
docker stop "$CONTAINER_NAME" >/dev/null 2>&1 || true
fi
fi
stop_pg
die "没有切换,仍用 SQLite(数据目录里的 agentlab.db 没动过)。照上面的报错处理好之后重新运行 ./deploy.sh migrate-to-postgres,
重复执行是安全的:内置库里这次导了一半的会先清空再导"
}
copy_to_pg() {
# --assume-stopped:服务是这里刚停的(强杀留下的 -wal 也不挡);快照放数据目录里(和库同一块盘,空间够)。
# 内置库是直连(没有 PgBouncer),断点跟着目标地址走,不用 --direct-url。
# 逐表的结果里来源是空表的几十行不列(没什么可核对的),别的原样打出来;退出码照 copy-to-postgres 的(pipefail)
docker run --rm --network "$DOCKER_NETWORK" -v "$DATA_ABS:/data" -e "PGPASSFILE=$PG_PASSFILE" \
--entrypoint python "$IMAGE" -m app.db copy-to-postgres /data \
"postgresql+asyncpg://$PG_USER@$POSTGRES_CONTAINER:5432/$PG_DB" --assume-stopped --work-dir /data "$@" \
| grep -v ' 空表$'
}
cmd_migrate_to_postgres() {
check_docker
check_arch
read_env
ensure_image
prepare_data
check_existing
[ -z "$EXTERNAL_DB" ] || die "agentlab.env 里设了 ${EXTERNAL_DB}(外接 PostgreSQL)。内置和外接只能选一种:要切到内置的,先删掉那一行;
要搬进外接的库,用镜像里的 python -m app.db copy-to-postgres(见 README「用 PostgreSQL」)"
# 切过去就是内置库:和它对不上的设置(PgBouncer 开关)先拦下,别停了服务才发现
check_db_settings builtin
local state
state="$(stored_state)"
if [ "$state" = builtin ]; then
say "这个数据目录已经切到内置 PostgreSQL 了,什么都不用做(./deploy.sh status 看状态)"
return 0
fi
[ -e "$DATA_ABS/agentlab.db" ] || die "数据目录 $DATA_ABS 里没有 SQLite 的库(agentlab.db),没有可搬的。新部署直接用 ./deploy.sh install --postgres"
# 数据卷已经有了、又不是这个数据目录上次没切成留下的:里面可能是别人的数据,下面要清空它,不能碰
if [ "$state" != migrating ] && volume_exists "$POSTGRES_VOLUME"; then
die "docker 数据卷 $POSTGRES_VOLUME 已经存在,不是这个数据目录上次没切成留下的(多半是以前卸载时留下的内置 PostgreSQL
的数据)。切换要清空内置库,为免删错数据,没有动它。
- 确定不要了:docker volume rm ${POSTGRES_VOLUME}(不可恢复),再运行;
- 要留着:agentlab.env 里另起一个 POSTGRES_VOLUME 的名字"
fi
if container_exists "$POSTGRES_CONTAINER"; then check_pg_is_ours; fi
fix_data_owner
ensure_pg_image
PG_APPLY_IMAGE=1
container_exists "$CONTAINER_NAME" && MIGRATE_HAD_APP=1
[ "$(container_state "$CONTAINER_NAME")" = running ] && MIGRATE_WAS_RUNNING=1
say "1/6 停服务(导入要在服务停着时做)"
stop_app
say "2/6 备份 SQLite 库"
backup_sqlite || migrate_rollback "SQLite 库备份失败"
say "3/6 起内置 PostgreSQL"
( pg_secrets ) || migrate_rollback "没能生成内置 PostgreSQL 的密码"
ops state --set migrating >/dev/null || migrate_rollback "没能在数据目录里记下「开始切换」"
( start_pg ) || migrate_rollback "内置 PostgreSQL 没起来"
# 内置库里要是有东西,只能是上次没切成留下的半份(上面查过数据卷),清空重来
docker exec "$POSTGRES_CONTAINER" psql -q -U "$PG_USER" -d postgres -v ON_ERROR_STOP=1 \
-c "DROP DATABASE IF EXISTS \"$PG_DB\" WITH (FORCE)" -c "CREATE DATABASE \"$PG_DB\" OWNER \"$PG_USER\"" >/dev/null \
|| migrate_rollback "没能清空内置库里上次留下的数据"
say "4/6 先核对(只数行数,不写)"
copy_to_pg --dry-run || migrate_rollback "核对没过"
say "5/6 导入并逐表核对"
copy_to_pg || migrate_rollback "导入或核对没过"
MIGRATE_DEPLOYING=1
ops state --set builtin >/dev/null || migrate_rollback "没能在数据目录里记下「已切到内置 PostgreSQL」"
say "6/6 按内置 PostgreSQL 起服务"
resolve_mode
decide_microvm
( deploy_container ) || migrate_rollback "按内置 PostgreSQL 起的服务没通过健康检查"
echo
say "已切到内置 PostgreSQL。SQLite 的库文件(agentlab.db、checkpoints.db)原样留在 $DATA_ABS 里、不再使用,"
echo " 另有一份备份在 backups/sqlite/。用一段时间确认没问题后再删(见 README「用 PostgreSQL」)"
}
# start / stop / restart / status / logs / uninstall:数据目录看容器实际挂的,没有容器再看配置
# 这几个只管容器,不改配置:模式照数据目录里记的认,agentlab.env 和它冲突(内置的又设了外接地址)也不在这里拦,留给 install
locate_data() {
DATA_ABS=""
if container_exists "$CONTAINER_NAME"; then
DATA_ABS="$(data_source_of "$CONTAINER_NAME")"
OPS_IMAGE="$(docker inspect -f '{{.Config.Image}}' "$CONTAINER_NAME")"
fi
if [ -z "$DATA_ABS" ] && [ -d "$DATA_PATH" ]; then DATA_ABS="$(cd "$DATA_PATH" && pwd -P)"; fi
MODE="sqlite"
if [ -n "$DATA_ABS" ] && [ "$(stored_mode)" = builtin ]; then
MODE="builtin"
elif [ -n "$EXTERNAL_DB" ]; then
MODE="external"
fi
}
wait_app() {
if wait_healthy "$CONTAINER_NAME"; then
say "已启动"; print_access
say "$1"; print_access
else
show_failure; die "容器没通过健康检查"
fi
}
cmd_start() {
check_docker; read_env; require_container; locate_data
[ "$MODE" != builtin ] || start_pg
docker start "$CONTAINER_NAME" >/dev/null
wait_app "已启动"
}
cmd_stop() {
check_docker; read_env; require_container
check_docker; read_env; require_container; locate_data
# 先停服务再停库:服务收尾时还要写库
say "停止 ${CONTAINER_NAME}(数据保留)"
docker stop "$CONTAINER_NAME" >/dev/null
[ "$MODE" != builtin ] || stop_pg
say "已停止。开机也不会自动起来,要用时运行 ./deploy.sh start"
}
# 缺省只重启服务:库不用跟着断一次(库停着的话先把它起来,服务才连得上)。--postgres 连库一起重启
cmd_restart() {
check_docker; read_env; require_container
say "重启 $CONTAINER_NAME"
docker restart "$CONTAINER_NAME" >/dev/null
if wait_healthy "$CONTAINER_NAME"; then
say "已重启"; print_access
check_docker; read_env; require_container; locate_data
if [ -n "$RESTART_POSTGRES" ]; then
[ "$MODE" = builtin ] || die "这个部署没用内置 PostgreSQL,--postgres 没有可重启的库。只重启服务:./deploy.sh restart"
say "重启 $CONTAINER_NAME 和内置 PostgreSQL(${POSTGRES_CONTAINER})"
stop_app
stop_pg
start_pg
docker start "$CONTAINER_NAME" >/dev/null
else
show_failure; die "容器没通过健康检查"
say "重启 $CONTAINER_NAME"
if [ "$MODE" = builtin ] && [ "$(container_state "$POSTGRES_CONTAINER")" != running ]; then
start_pg
fi
docker restart "$CONTAINER_NAME" >/dev/null
fi
wait_app "已重启"
}
cmd_status() {
@@ -560,6 +1074,7 @@ cmd_status() {
echo "没有名为 $CONTAINER_NAME 的容器(还没部署,或已卸载)。部署:./deploy.sh install"
exit 1
fi
locate_data
local state health image src
state="$(container_state "$CONTAINER_NAME")"
health=""
@@ -572,22 +1087,42 @@ cmd_status() {
echo "镜像 $image"
echo "端口 $(docker port "$CONTAINER_NAME" 8000/tcp 2>/dev/null | tr '\n' ' ')"
echo "数据目录 ${src:-(未挂载)}"
echo "应用库 $(mode_label)"
if [ -n "$DATA_ABS" ] && [ "$MODE" = sqlite ] && [ "$(stored_state)" = migrating ]; then
echo " 上次 migrate-to-postgres 没切成(仍用 SQLite),数据卷 $POSTGRES_VOLUME 里留着导了一半的;重新运行会清空重来"
fi
if [ "$MODE" = builtin ]; then
local pstate phealth pimage
pstate="$(container_state "$POSTGRES_CONTAINER")"
phealth=""
[ "$pstate" != running ] || phealth="$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{end}}' "$POSTGRES_CONTAINER")"
pimage="$(docker inspect -f '{{.Config.Image}}' "$POSTGRES_CONTAINER" 2>/dev/null || echo "$POSTGRES_IMAGE")"
echo "内置库 $POSTGRES_CONTAINER ${pstate}${phealth:+(pg_isready:${phealth})},镜像 ${pimage},网络 ${DOCKER_NETWORK}(端口不对外)"
echo "库的备份 ${src:-$DATA_ABS}/backups/postgres/(upgrade 前自动 pg_dump,留最近 $BACKUP_KEEP 份)"
fi
[ "$state" != running ] || echo "代码沙箱 $(sandbox_summary)"
echo "这个包 $IMAGE"
if [ "$state" = running ]; then print_access; fi
}
cmd_logs() {
check_docker; read_env; require_container
check_docker; read_env
local target="$CONTAINER_NAME"
if [ -n "$LOGS_POSTGRES" ]; then
target="$POSTGRES_CONTAINER"
container_exists "$target" || die "没有名为 $target 的容器:这个部署没用内置 PostgreSQL"
else
require_container
fi
local args=(--tail "$TAIL")
[ -z "$FOLLOW" ] || args+=(--follow)
# exec:Ctrl-C 直接交给 docker logs,不留一个还在跟随的子进程
exec docker logs "${args[@]}" "$CONTAINER_NAME"
exec docker logs "${args[@]}" "$target"
}
cmd_uninstall() {
check_docker; read_env
local src="" name
local src="" name pg=""
if container_exists "$CONTAINER_NAME"; then
check_is_agentlab
src="$(data_source_of "$CONTAINER_NAME")"
@@ -598,23 +1133,40 @@ cmd_uninstall() {
docker rm -f "$name" >/dev/null
fi
done
if container_exists "$POSTGRES_CONTAINER"; then
check_pg_is_ours
say "删除内置 PostgreSQL 的容器 ${POSTGRES_CONTAINER}(数据卷 $POSTGRES_VOLUME 留着)"
docker rm -f "$POSTGRES_CONTAINER" >/dev/null
pg=1
fi
if docker network inspect "$DOCKER_NETWORK" >/dev/null 2>&1; then
docker network rm "$DOCKER_NETWORK" >/dev/null 2>&1 && say "删除 docker 网络 $DOCKER_NETWORK" \
|| warn "docker 网络 $DOCKER_NETWORK 没删掉(可能还有别的容器连着)"
fi
if [ -n "$PURGE_IMAGE" ]; then
if image_present; then
say "删除镜像 $IMAGE"
docker rmi "$IMAGE" >/dev/null || warn "镜像 $IMAGE 没删掉(可能还有别的容器在用)"
fi
# PostgreSQL 的镜像不删:本机别的东西可能也在用同一个镜像
else
echo "镜像 $IMAGE 保留着,重新部署不用再导入。要删:./deploy.sh uninstall --purge-image"
fi
[ -n "$src" ] || src="$DATA_PATH"
echo
echo "数据没有删,还在:$src"
echo "确定不要了再手动删除(不可恢复):sudo rm -rf '$src'"
if [ -n "$pg" ] || docker volume inspect "$POSTGRES_VOLUME" >/dev/null 2>&1; then
echo "内置 PostgreSQL 的数据在 docker 数据卷 $POSTGRES_VOLUME 里,也没有删"
echo "确定不要了再手动删除(不可恢复):sudo rm -rf '$src' && docker volume rm $POSTGRES_VOLUME"
else
echo "确定不要了再手动删除(不可恢复):sudo rm -rf '$src'"
fi
}
case "$CMD" in
install) cmd_install ;;
upgrade) cmd_upgrade ;;
migrate-to-postgres) cmd_migrate_to_postgres ;;
start) cmd_start ;;
stop) cmd_stop ;;
restart) cmd_restart ;;