feat(deploy): 新增 ipass-agent.py —— 跑在 .11 的远程更新控制面(HTTP)

把 update-ipass.sh 的动作暴露成 HTTP 接口,远端(AI/值班人)不必登录服务器即可
完成「拉镜像 → 重启 → 看日志 → 回滚」,形成「本机构建推送 → 远程自更新 → 自验证」闭环。

- 单文件、仅 Python 标准库(无 Flask/requests);Bearer token 鉴权,token 落
  ~/.ipass-agent-token(600);--bg 双 fork + setsid 真后台,另有 --stop/--check。
- 端点:/health /check /status /containers /logs /data(脱敏) /jobs[/id] /pull /update
  /rollback /restart。
- 变更类接口为异步任务(返 job id,/jobs/<id>?offset=N 增量取日志);
  同一时刻只允许一个变更任务,并发返回 409。
- 端口/挂载/网络/env/重启策略全部从旧容器 docker inspect 复刻;自定义 env 保留、
  Docker 自带的不照抄;动手前自动备份数据 + 打 rollback-<时间> 标签。

修掉两个真实隐患:
- HTTP/1.1 下鉴权失败的请求体若不消费,残包会被当作下一个请求的请求行 → 响应串包
  (已在 _dispatch 开头统一读掉 body)。
- 端口映射同一 host:container 在 inspect 中含 IPv4/IPv6 两条,不去重会重复 -p。

本机用真实流程验证:自动探测 → update 7 步全过(端口/自定义 env 复刻)→ rollback
回到旧镜像 → restart/logs/data 脱敏 → 409 并发保护 → 同连接残包测试 → --bg/--stop。

文档:readme §12.5 / §16、CLAUDE.md 新增「远程控制面」小节。
This commit is contained in:
admin committed 2026-09-12 10:20:49 +08:00
1 parent b5386283f7
commit 5e8c38aef4
3 files changed
+1135

No files matched your search

+32
View File
@@ -394,6 +394,38 @@ bash update-ipass.sh --bg # 后台更新(日志 ~/ipass-update-<时间>.l
> 验证脚本本身:本机用 `NAME=ipass-dt HOST_PORT=<高位> DATA_DIR=/tmp/... SKIP_PULL=1`
> 跑一遍即可(`SKIP_PULL=1` 用本地镜像,避免误部署旧 tag)。
### 远程控制面(更推荐):`deploy/ipass-agent.py`
跑在 **.11 上的常驻 HTTP 服务**(默认 `:18099`),把上面那套动作变成接口,**AI 可以直接
远程 pull / 更新 / 回滚 / 看日志**,形成「本机构建推送 → 远程更新 → 远程自验证」闭环,
不必每次找人登服务器。单文件、仅标准库、Bearer token 鉴权。
```bash
# 在 .11 上
python3 ipass-agent.py --check # 探测(不动任何东西)
python3 ipass-agent.py --bg # 后台常驻,日志 ~/ipass-agent.log
python3 ipass-agent.py --stop
# 在本地(AI 用)
A=http://192.168.1.11:18099; T='Authorization: Bearer <token>'
curl -s -H "$T" $A/status
curl -s -H "$T" -H 'Content-Type: application/json' -d '{"image":"<镜像>"}' $A/update # → job id
curl -s -H "$T" $A/jobs/<id>?offset=0 # 增量拉执行日志
curl -s -H "$T" -H 'Content-Type: application/json' -d '{}' $A/rollback
```
- **异步任务模型**:变更类 `POST` 立刻返回 `{"job":id}`,日志从 `/jobs/<id>?offset=N` 增量取;
**同时只允许一个变更任务**(并发第二个 → 409),因为两个 update 并发删容器会互相踩。
- **HTTP/1.1 必须先把请求体读掉再应答**(哪怕是 401):不读的话残包会被当成下一个请求的
请求行 → 响应串包。改 Handler 时别把 `_read_body()` 从 `_dispatch` 开头挪走。
- 端口/挂载/env/网络/重启策略从旧容器 `docker inspect` 复刻;动手前自动备份 + 打 rollback 标签。
- `/data` 对 `api_key` 脱敏,但 `domains.json` 原样返回 —— 服务等价 docker 权限,**必须设 token
且只在内网监听**,绝不上公网。
- 本机自测夹具做法:造 `ipass-dt` 容器(高位端口 + `/tmp` 数据目录),`--port` 用 18449,
`IPASS_AGENT_TOKEN=xxx` 固定 token,`POST /update` 带 `skip_pull:true` + 本地镜像。
注意 `echo "$JSON" | python3` 在 **zsh 下会把 `\r` 还原成真回车**导致 JSON 解析报错 ——
那是测试命令的问题,不是服务的 bug(用文件或 `printf '%s'` 传)。
## 本机验证夹具(改完必跑)
夹具**在仓库里**(`tests/`),不再放 `/tmp` —— 那儿的脚本一重启就没了,也没法 review。
File diff suppressed because it is too large. Load diff
+70
View File
@@ -547,6 +547,63 @@ bash update-ipass.sh --bg # 后台更新(日志落 ~/ipass-update-<时
- 旧容器若由 compose 创建,脚本会提示「已改用 docker run 接管」,想继续用 compose
请改用 `docker compose -f <file> up -d --force-recreate`。
### 12.5 远程更新控制面(ipass-agent)
`deploy/ipass-agent.py` —— 跑在 .11 上的**常驻 HTTP 服务**,把 §12.4 那套动作暴露成接口,
让**远端(AI / 值班人)不必登录服务器**就能完成「拉镜像 → 重启 → 看日志 → 回滚」,
形成「本机构建推送 → 远程自更新 → 远程自验证」的闭环(不必每次找人上机器操作)。
```bash
# 拷到 .11 后(用有 docker 权限的账号跑)
python3 ipass-agent.py --check # 只探测:打印容器/端口/数据目录,不动任何东西
python3 ipass-agent.py --bg # 后台常驻,默认 0.0.0.0:18099
python3 ipass-agent.py --bg --name ipass --data-dir /opt/ipass/data
python3 ipass-agent.py --stop # 停止
tail -f ~/ipass-agent.log # 日志(pid 在 ~/ipass-agent.pid)
```
- 单文件、**只用 Python 标准库**(不需要 Flask / requests),有 `python3` 就能跑。
- **鉴权**:除 `/health` 外全部要 `Authorization: Bearer <token>`;token 首次启动随机生成并写入
`~/.ipass-agent-token`(权限 600),也可用 `--token` 或环境变量 `IPASS_AGENT_TOKEN` 指定。
- 端口/挂载/网络/env/重启策略**全部从旧容器 `docker inspect` 复刻**,不写死任何参数;
自定义 env 会保留,Docker 自带的(PATH / NGINX_VERSION…)不会照抄。
- 变更类接口是**异步任务**:立刻返回 `{"job":"<id>"}`,用 `GET /jobs/<id>?offset=N` 增量拉日志。
**同一时刻只允许一个变更任务**(第二个返回 409),避免并发删容器互相踩。
- 动手前自动 `tar` 备份数据目录、给旧镜像打 `ipass-gateway:rollback-<时间>` 标签。
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/health` | 存活 + 版本(**免鉴权**) |
| GET | `/` | 服务信息 + 端点清单 |
| GET | `/check` | 探测(dry-run),等价 `--check` |
| GET | `/status` | 容器状态 + 镜像 digest + 数据摘要 + 宿主探活 |
| GET | `/containers` | 容器列表(只留与 ipass/nginx 相关的) |
| GET | `/logs?tail=200` | 容器日志 |
| GET | `/data?file=users\|domains\|upstreams` | 数据文件摘要(**`api_key` 已脱敏**) |
| GET | `/jobs?limit=5`、`/jobs/<id>?offset=N` | 任务列表 / 任务详情 + 增量日志 |
| POST | `/pull` | `{image, registry_user?, registry_pass?}` → 只拉镜像 |
| POST | `/update` | `{image?, skip_pull?, name?, data_dir?, host_port?}` → 完整更新 |
| POST | `/rollback` | `{tag?}` → 回滚到最近(或指定)的 `rollback-*` 镜像 |
| POST | `/restart` | 只重启容器(同步返回) |
典型远程调用:
```bash
A=http://192.168.1.11:18099; T='Authorization: Bearer <token>'
curl -s -H "$T" $A/status # 先看现状
curl -s -H "$T" -H 'Content-Type: application/json' \
-d '{"image":"crpi-…/ssw188/nginx:ipass-1.0.0"}' $A/update # 更新,返回 job id
curl -s -H "$T" $A/jobs/<job-id> # 拉执行日志(7 步全记录)
curl -s -H "$T" -H 'Content-Type: application/json' -d '{}' $A/rollback # 出事回滚
```
**安全**:这个服务能删/起容器,**等价服务器上的 docker 权限**,务必做到
① **必须设 token**(别用空/弱口令);② 只在内网监听(默认 `0.0.0.0`,可 `--bind 127.0.0.1`
或加防火墙);③ **绝不暴露到公网**。`/data` 对 `api_key` 已脱敏,但 `domains.json` 会原样返回。
> `update-ipass.sh`(§12.4)仍然保留:没有 python3、或服务没起来时的应急手段。
---
## 13. 安全
@@ -729,6 +786,19 @@ curl -s -H "X-API-Key: $KEY" "$API/api/v1/usage"
## 16. 变更记录
- **2026-09-12 远程更新控制面 `deploy/ipass-agent.py`(跑在 .11 的 HTTP 服务)**
- 把 §12.4 的更新动作暴露成 HTTP 接口,远端可自助完成「拉镜像 → 重启 → 看日志 → 回滚」,
不再需要每次人工登录服务器操作(见 §12.5)。
- 单文件、仅 Python 标准库;Bearer token 鉴权(`~/.ipass-agent-token`,600);
`--bg` 双 fork + `setsid` 真后台,另有 `--stop` / `--check`。
- 变更类接口为异步任务(`POST` 返 `job id`,`GET /jobs/<id>?offset=N` 增量拉日志);
**同一时刻只允许一个变更任务**,并发请求返回 409。
- 端口/挂载/网络/env/重启策略全部从旧容器 `docker inspect` 复刻(自定义 env 保留、
Docker 自带的不照抄);动手前自动备份数据 + 打 `rollback-<时间>` 标签。
- 修掉两个真实隐患:① HTTP/1.1 下鉴权失败的请求体不消费会把残包当成下一个请求(串包);
② 端口映射同一 host:container 在 inspect 里有 IPv4/IPv6 两条,不去重会重复 `-p`。
- 本机用真实流程验证:自动探测 → update(7 步全过、env/端口复刻)→ rollback 回到旧镜像
→ restart / logs / data 脱敏 → 409 并发保护 → 同连接残包测试 → `--bg`/`--stop`。
- **2026-09-12 一键更新脚本 `deploy/update-ipass.sh`(.11 部署用)**
- 拉新镜像 → `tar` 备份数据 → 删旧容器 → **按旧容器复刻端口/挂载/网络**起新容器 → 自检。
- 参数全部自动探测(读 `docker inspect` 静态配置,**停止态容器也能正确识别**;