From 5e8c38aef4ef84eeec69d69802386bb88cd7b1cf Mon Sep 17 00:00:00 2001 From: admin Date: Sat, 12 Sep 2026 10:20:49 +0800 Subject: [PATCH] =?UTF-8?q?feat(deploy):=20=E6=96=B0=E5=A2=9E=20ipass-agen?= =?UTF-8?q?t.py=20=E2=80=94=E2=80=94=20=E8=B7=91=E5=9C=A8=20.11=20?= =?UTF-8?q?=E7=9A=84=E8=BF=9C=E7=A8=8B=E6=9B=B4=E6=96=B0=E6=8E=A7=E5=88=B6?= =?UTF-8?q?=E9=9D=A2=EF=BC=88HTTP=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 把 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/?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 新增「远程控制面」小节。 --- CLAUDE.md | 32 ++ deploy/ipass-agent.py | 1033 +++++++++++++++++++++++++++++++++++++++++ readme.md | 70 +++ 3 files changed, 1135 insertions(+) create mode 100644 deploy/ipass-agent.py diff --git a/CLAUDE.md b/CLAUDE.md index 4b61776..29222f1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 ' +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/?offset=0 # 增量拉执行日志 +curl -s -H "$T" -H 'Content-Type: application/json' -d '{}' $A/rollback +``` + +- **异步任务模型**:变更类 `POST` 立刻返回 `{"job":id}`,日志从 `/jobs/?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。 diff --git a/deploy/ipass-agent.py b/deploy/ipass-agent.py new file mode 100644 index 0000000..626e17b --- /dev/null +++ b/deploy/ipass-agent.py @@ -0,0 +1,1033 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +""" +ipass-agent — iPass 容器远程更新控制面 + +跑在宿主机上,暴露一个 HTTP 端口,让远端(AI / 人)可以自助完成: + + docker pull → 备份数据 → 留回滚标签 → 删旧容器 + → 按旧容器复刻端口/挂载/网络/env 起新容器 → 自检 + +单文件、只依赖 Python 标准库 + `docker` CLI。**不需要** Flask / requests。 + +-------------------------------------------------------------------------------- +用法 +-------------------------------------------------------------------------------- + python3 ipass-agent.py --check # 只探测(不起服务),打印容器/端口/数据目录 + python3 ipass-agent.py # 前台起服务,默认 0.0.0.0:18099 + python3 ipass-agent.py --bg # 后台起服务,日志 ~/ipass-agent.log + python3 ipass-agent.py --stop # 停掉后台服务 + python3 ipass-agent.py --port 18099 --name ipass --data-dir ~/ipass/data + +-------------------------------------------------------------------------------- +鉴权 +-------------------------------------------------------------------------------- +除 /health 外所有端点都要请求头: + Authorization: Bearer +token 取值顺序:--token > 环境变量 IPASS_AGENT_TOKEN > ~/.ipass-agent-token +(文件不存在时随机生成并写入,权限 600) + +-------------------------------------------------------------------------------- +端点一览 +-------------------------------------------------------------------------------- + GET /health 存活 + 版本(免鉴权) + GET / 服务信息 + 端点清单 + GET /check 探测(dry-run):容器 / 端口 / 挂载 / 数据摘要 + GET /status 当前容器状态 + 镜像 digest + 数据摘要 + 宿主探活 + GET /containers 所有候选容器(名字或镜像含 ipass) + GET /logs?tail=200 容器日志 + GET /data?file=users 数据文件摘要(api_key 已脱敏) + GET /jobs?limit=5 最近任务列表 + GET /jobs/?offset=N 任务详情 + 增量日志 + POST /pull {"image":...} 拉镜像(异步任务) + POST /update {"image":...,"skip_pull":...} 完整更新(异步任务) + POST /rollback {"tag":...} 回滚到 rollback 标签(异步任务) + POST /restart 只重启容器(同步) + +任务(job)在同一时刻**只允许一个**在跑,避免并发删容器互相踩。 +""" + +import argparse +import hmac +import http.client +import json +import os +import random +import re +import shutil +import ssl +import string +import subprocess +import sys +import tarfile +import threading +import time +from http.server import BaseHTTPRequestHandler, HTTPServer +from socketserver import ThreadingMixIn +from urllib.parse import urlparse, parse_qs + +# ------------------------------------------------------------------ 常量 + +SERVICE = "ipass-agent" +VERSION = "1.0.0" + +DEFAULT_PORT = 18099 +DEFAULT_IMAGE = ("crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/" + "ssw188/nginx:ipass-1.0.0") +DEFAULT_CONTAINER = "ipass" + +CONTAINER_DATA = "/usr/local/nginx/data" # 容器内数据目录 +MAIN_CPORT = "18098" # 容器内主端口(宿主映射到它) +NGINX_BIN = "/usr/local/nginx/sbin/nginx" +ADMIN_HOST = "mdm.mayishangshu.cn" # 探活用的 Host 头 + +ROLLBACK_PREFIX = "ipass-gateway:rollback-" +JOB_KEEP = 20 +PULL_TIMEOUT = 1800 + +# Docker 自己注入的 env,复刻容器时不能照抄 +DOCKER_BUILTIN_ENV = { + "PATH", "HOSTNAME", "HOME", "NGINX_VERSION", "NJS_VERSION", + "PKG_RELEASE", "NJS_RELEASE", "SSL_CERT_FILE", "PWD", "TERM", +} + + +# ------------------------------------------------------------------ 基础工具 + +def now_ts(): + return int(time.time()) + + +def ts_tag(): + return time.strftime("%Y%m%d-%H%M%S") + + +def find_docker(): + p = shutil.which("docker") + if p: + return p + for c in ("/usr/bin/docker", "/usr/local/bin/docker", "/snap/bin/docker"): + if os.path.exists(c): + return c + return "docker" + + +DOCKER = find_docker() + + +def docker(args, timeout=120, stdin_data=None): + """执行 docker 命令,返回 (rc, 合并输出文本)。""" + try: + p = subprocess.run( + [DOCKER] + list(args), + stdout=subprocess.PIPE, stderr=subprocess.STDOUT, + input=stdin_data, timeout=timeout, + ) + return p.returncode, p.stdout.decode("utf-8", "replace") + except subprocess.TimeoutExpired: + return 124, "command timeout after %ss: docker %s" % (timeout, " ".join(args)) + except Exception as e: # noqa: BLE001 + return 127, "docker 调用失败: %s" % e + + +def sh(args, timeout=120): + try: + p = subprocess.run(args, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, + timeout=timeout) + return p.returncode, p.stdout.decode("utf-8", "replace") + except Exception as e: # noqa: BLE001 + return 127, str(e) + + +def clean_lines(text): + """docker pull 的进度条会刷 \\r,清一下再进日志。""" + out = [] + for raw in text.replace("\r", "\n").split("\n"): + s = raw.rstrip() + if s: + out.append(s) + return out + + +def http_probe(port, path="/api/admin/users", host=ADMIN_HOST, timeout=5): + """从宿主机探活容器暴露的端口。返回 HTTP 状态码,0 表示连不上。""" + if not port: + return 0 + try: + ctx = ssl._create_unverified_context() + conn = http.client.HTTPSConnection("127.0.0.1", int(port), timeout=timeout, + context=ctx) + conn.request("GET", path, headers={"Host": host}) + r = conn.getresponse() + r.read() + conn.close() + return r.status + except Exception: # noqa: BLE001 + return 0 + + +# ------------------------------------------------------------------ 容器探测 + +def list_containers(): + """列出所有容器:[(name, image, status)]""" + rc, out = docker(["ps", "-a", "--format", + "{{.Names}}\t{{.Image}}\t{{.Status}}"]) + if rc != 0: + return [] + res = [] + for line in out.splitlines(): + parts = line.split("\t") + if len(parts) >= 3: + res.append((parts[0], parts[1], parts[2])) + elif len(parts) == 2: + res.append((parts[0], parts[1], "")) + return res + + +def relevant_containers(exclude=None): + """只挑可能跟 ipass 相关的容器,过滤掉 k8s_* / 其它项目的噪音。""" + out = [] + for n, i, s in list_containers(): + if exclude and n == exclude: + continue + blob = (n + " " + (i or "")).lower() + if "ipass" in blob or "nginx" in blob: + out.append({"name": n, "image": i, "status": s}) + return out[:8] + + +def detect_container(prefer=None): + """找 ipass 容器:prefer 命中优先,其次名字/镜像含 ipass。""" + conts = list_containers() + if not conts: + return None + if prefer: + for n, _i, _s in conts: + if n == prefer: + return n + hits = [n for n, img, _s in conts + if "ipass" in n.lower() or "ipass" in (img or "").lower()] + if len(hits) == 1: + return hits[0] + if hits: + # 多个候选时优先「在跑的」,再优先名字最短的 + running = [n for n, _i, s in conts if n in hits and s.lower().startswith("up")] + pool = running or hits + return sorted(pool, key=len)[0] + return None + + +def inspect_one(name): + rc, out = docker(["inspect", name]) + if rc != 0: + return None + try: + arr = json.loads(out) + return arr[0] if arr else None + except Exception: # noqa: BLE001 + return None + + +def image_repo_digest(image): + rc, out = docker(["image", "inspect", "--format", "{{json .RepoDigests}}", image]) + if rc != 0: + return None + try: + arr = json.loads(out.strip() or "[]") + return arr[0] if arr else None + except Exception: # noqa: BLE001 + return None + + +def image_exists(image): + rc, _ = docker(["image", "inspect", image]) + return rc == 0 + + +# ------------------------------------------------------------------ 从 inspect 复刻启动参数 + +def extract_ports(cfg, main_port_override=None): + """返回 ([docker run 端口参数], 宿主主端口)。 + + 注意:`docker inspect` 里同一个映射会带 IPv4 与 IPv6 两条, + 不去重就会生成重复的 -p → 「address already in use」。 + """ + pb = (cfg.get("HostConfig") or {}).get("PortBindings") or {} + seen, args, main = set(), [], None + for cport, binds in pb.items(): + cnum = cport.split("/")[0] + for b in binds or []: + hip = (b.get("HostIp") or "").strip() + hp = (b.get("HostPort") or "").strip() + if not hp: + continue + if main_port_override and cnum == MAIN_CPORT: + hp = str(main_port_override) + if hip in ("", "0.0.0.0", "::"): + key = "%s:%s" % (hp, cnum) + else: + key = "%s:%s:%s" % (hip, hp, cnum) + if key in seen: + continue + seen.add(key) + args += ["-p", key] + if cnum == MAIN_CPORT: + main = hp + if main is None and args: + main = args[1].split(":")[0] + return args, main + + +def extract_mounts(cfg): + """返回 (数据目录源, [其余挂载参数])。""" + data_src, extra = None, [] + for m in cfg.get("Mounts") or []: + dest = m.get("Destination") or "" + if dest == CONTAINER_DATA: + data_src = m.get("Source") or m.get("Name") + continue + if m.get("Type") == "volume": + spec = "%s:%s" % (m.get("Name"), dest) + else: + spec = "%s:%s" % (m.get("Source"), dest) + if m.get("RW") is False: + spec += ":ro" + extra += ["-v", spec] + return data_src, extra + + +def extract_env(cfg, image): + """只复刻「用户自己加的」env(剔除 Docker/镜像自带的)。""" + env = (cfg.get("Config") or {}).get("Env") or [] + base = set(DOCKER_BUILTIN_ENV) + if image: + rc, out = docker(["image", "inspect", "--format", "{{json .Config.Env}}", image]) + if rc == 0: + try: + base |= set(json.loads(out.strip() or "[]")) + except Exception: # noqa: BLE001 + pass + return [e for e in env if e.split("=", 1)[0] not in base] + + +def extract_net(cfg): + mode = (cfg.get("HostConfig") or {}).get("NetworkMode") or "" + if mode in ("", "default", "bridge"): + return [] + return ["--network", mode] + + +def extract_restart(cfg): + rp = (cfg.get("HostConfig") or {}).get("RestartPolicy") or {} + return rp.get("Name") or "" + + +# ------------------------------------------------------------------ 数据摘要 / 备份 + +def read_json(path): + try: + with open(path, "r", encoding="utf-8") as f: + return json.load(f) + except Exception: # noqa: BLE001 + return None + + +def data_summary(data_dir): + if not data_dir: + return {"error": "未知数据目录"} + users = read_json(os.path.join(data_dir, "users.json")) + domains = read_json(os.path.join(data_dir, "domains.json")) + ups = read_json(os.path.join(data_dir, "llm-upstreams.json")) + return { + "dir": data_dir, + "writable": os.access(data_dir, os.W_OK) if os.path.isdir(data_dir) else False, + "users": len(users) if isinstance(users, dict) else None, + "domains": len(domains) if isinstance(domains, list) else None, + "upstreams": len(ups) if isinstance(ups, dict) else None, + } + + +def mask_key(k): + if not k: + return "" + return k[:10] + "…" if len(k) > 12 else "***" + + +def data_view(data_dir, which): + fname = {"users": "users.json", "domains": "domains.json", + "upstreams": "llm-upstreams.json"}.get(which) + if not fname: + return None + raw = read_json(os.path.join(data_dir, fname)) + if raw is None: + return None + if which == "users" and isinstance(raw, dict): + out = {} + for name, u in raw.items(): + out[name] = { + "role": u.get("role"), + "display_name": u.get("display_name", ""), + "api_key": mask_key(u.get("api_key")), + "allowed_models": u.get("allowed_models"), + "llm_rpm": u.get("llm_rpm"), + "llm_daily": u.get("llm_daily"), + "temp_grant_until": u.get("temp_grant_until"), + "has_password": bool(u.get("pwd_hash")), + } + return out + if which == "upstreams" and isinstance(raw, dict): + out = {} + for slot, u in raw.items(): + out[slot] = { + "base": u.get("base"), + "enabled": u.get("enabled"), + "models": u.get("models"), + "note": u.get("note", ""), + "has_auth": bool(u.get("auth")), + } + return out + return raw + + +def backup_data(data_dir, job): + if not data_dir or not os.path.isdir(data_dir): + jlog(job, " ! 数据目录不存在,跳过备份:%s" % data_dir) + return None + dest = os.path.join(os.path.expanduser("~"), "ipass-data-backup-%s.tar.gz" % ts_tag()) + try: + with tarfile.open(dest, "w:gz") as tf: + tf.add(data_dir, arcname="data") + size = os.path.getsize(dest) + jlog(job, " 已备份 %s(%.1f KB)" % (dest, size / 1024.0)) + return dest + except Exception as e: # noqa: BLE001 + jlog(job, " ! 备份失败(继续,但请留意):%s" % e) + return None + + +# ------------------------------------------------------------------ 任务(job) + +JOBS = {} +JOBS_ORDER = [] +JOBS_LOCK = threading.Lock() +ACTIVE = threading.Lock() + + +def jlog(job, msg): + line = "[%s] %s" % (time.strftime("%H:%M:%S"), msg) + with JOBS_LOCK: + job["log"].append(line) + if not BACK["quiet"]: + print(line, flush=True) + + +def new_job(kind, params): + jid = "%s-%s" % (ts_tag(), "".join(random.choice(string.hexdigits[:16]) + for _ in range(4))) + job = {"id": jid, "kind": kind, "state": "running", "rc": None, + "log": [], "created": now_ts(), "finished": None, "params": params, + "result": None} + with JOBS_LOCK: + JOBS[jid] = job + JOBS_ORDER.append(jid) + while len(JOBS_ORDER) > JOB_KEEP: + old = JOBS_ORDER.pop(0) + JOBS.pop(old, None) + return job + + +def start_job(kind, fn, params): + """起一个异步任务。同时只允许一个在跑,避免并发删容器。""" + if not ACTIVE.acquire(blocking=False): + return None, "已有任务在执行中(同一时刻只允许一个变更任务),稍后再试" + job = new_job(kind, params) + + def runner(): + try: + job["result"] = fn(job, params) + job["state"] = "done" + job["rc"] = 0 + except Exception as e: # noqa: BLE001 + jlog(job, "✗ 失败:%s" % e) + job["state"] = "failed" + job["rc"] = 1 + finally: + job["finished"] = now_ts() + ACTIVE.release() + + t = threading.Thread(target=runner) + t.daemon = True + t.start() + return job, None + + +# ------------------------------------------------------------------ 业务动作 + +def op_pull(job, p): + image = p.get("image") or DEFAULT_IMAGE + user, pwd = p.get("registry_user"), p.get("registry_pass") + if user and pwd: + registry = image.split("/")[0] + jlog(job, "→ docker login %s" % registry) + rc, out = docker(["login", registry, "-u", user, "--password-stdin"], + timeout=120, stdin_data=pwd.encode()) + jlog(job, " rc=%s" % rc) + for l in clean_lines(out): + jlog(job, " " + l) + jlog(job, "→ docker pull %s" % image) + rc, out = docker(["pull", image], timeout=PULL_TIMEOUT) + for l in clean_lines(out): + jlog(job, " " + l) + if rc != 0: + raise RuntimeError("docker pull 失败 rc=%s" % rc) + jlog(job, "收到镜像 digest:%s" % (image_repo_digest(image) or "(未知)")) + return {"image": image, "digest": image_repo_digest(image)} + + +def op_update(job, p): + name = p.get("name") or detect_container(BACK["name"]) + if not name: + raise RuntimeError("未发现 ipass 容器,请用 --name 指定或检查 docker ps -a") + image = p.get("image") or DEFAULT_IMAGE + skip_pull = bool(p.get("skip_pull")) + data_override = p.get("data_dir") + host_port = p.get("host_port") + + job["container"] = name + cfg = inspect_one(name) + if cfg is None: + raise RuntimeError("容器 %s 不存在" % name) + + old_image = (cfg.get("Config") or {}).get("Image") or "" + # ---- 计划 + data_src, extra_mounts = extract_mounts(cfg) + if data_override: + data_src = os.path.expanduser(str(data_override)) + port_args, main_port = extract_ports(cfg, host_port) + net_args = extract_net(cfg) + envs = extract_env(cfg, old_image) if old_image else [] + restart = extract_restart(cfg) or "always" + if "host" in net_args: + port_args, main_port = [], main_port or "88" + if not data_src: + raise RuntimeError("旧容器没挂 %s,拒绝更新(会丢数据)。用 DATA_DIR/--data-dir 指定" + % CONTAINER_DATA) + + job["plan"] = { + "container": name, "old_image": old_image, "new_image": image, + "ports": port_args, "main_port": main_port, "data_dir": data_src, + "extra_mounts": extra_mounts, "network": net_args, + "restart": restart, "env": [e.split("=", 1)[0] for e in envs], + } + + jlog(job, "== 更新计划 ==") + jlog(job, " 容器 %s" % name) + jlog(job, " 旧镜像 %s" % (old_image or "(未知)")) + jlog(job, " 新镜像 %s" % image) + jlog(job, " 端口 %s" % (" ".join(port_args) or "(无)")) + jlog(job, " 数据目录 %s -> %s" % (data_src, CONTAINER_DATA)) + if extra_mounts: + jlog(job, " 附加挂载 %s" % " ".join(extra_mounts)) + if net_args: + jlog(job, " 网络 %s" % " ".join(net_args)) + if envs: + jlog(job, " 附加环境 %s" % ", ".join(e.split("=", 1)[0] for e in envs)) + + # ---- 1 拉镜像 + if skip_pull: + jlog(job, "\n1/7 跳过拉取(skip_pull=1),校验本地镜像…") + if not image_exists(image): + raise RuntimeError("本地没有镜像 %s,无法跳过拉取" % image) + jlog(job, " 本地已有 %s" % image) + else: + jlog(job, "\n1/7 拉取镜像") + op_pull(job, {"image": image, "registry_user": p.get("registry_user"), + "registry_pass": p.get("registry_pass")}) + + # ---- 2 备份数据 + jlog(job, "\n2/7 备份数据") + job["backup"] = backup_data(data_src, job) + + # ---- 3 旧镜像留回滚标签 + jlog(job, "\n3/7 旧镜像留回滚标签") + rollback_tag = None + if old_image and old_image != image: + rollback_tag = "%s%s" % (ROLLBACK_PREFIX, ts_tag()) + rc, out = docker(["tag", old_image, rollback_tag]) + if rc == 0: + job["rollback_tag"] = rollback_tag + jlog(job, " %s → %s" % (old_image, rollback_tag)) + else: + jlog(job, " ! 打标签失败:%s" % out.strip()) + else: + jlog(job, " (旧镜像与新镜像相同或未知,跳过)") + + # ---- 4 删旧容器 + jlog(job, "\n4/7 停止并删除旧容器") + docker(["stop", "-t", "10", name], timeout=60) + rc, out = docker(["rm", "-f", name], timeout=60) + if rc != 0: + raise RuntimeError("删除旧容器失败:%s" % out.strip()) + jlog(job, " 已删除 %s" % name) + + # ---- 5 起新容器 + jlog(job, "\n5/7 起新容器") + argv = ["run", "-d", "--name", name] + if restart: + argv += ["--restart", restart] + argv += port_args + argv += ["-v", "%s:%s" % (data_src, CONTAINER_DATA)] + argv += extra_mounts + for e in envs: + argv += ["-e", e] + argv += net_args + argv += [image] + rc, out = docker(argv, timeout=120) + if rc != 0: + jlog(job, " ! 启动失败:%s" % out.strip()) + jlog(job, " 回滚命令:") + if rollback_tag: + jlog(job, " docker rm -f %s && docker run -d --name %s --restart %s %s " + "-v %s:%s %s" % (name, name, restart, " ".join(port_args), + data_src, CONTAINER_DATA, rollback_tag)) + raise RuntimeError("新容器启动失败 rc=%s" % rc) + jlog(job, " 新容器已启动(%s)" % out.strip()[:12]) + time.sleep(2) + + # ---- 6 容器内自检 + jlog(job, "\n6/7 容器内自检") + rc, out = docker(["exec", name, NGINX_BIN, "-t"]) + jlog(job, " nginx -t rc=%s %s" % (rc, (out.strip().splitlines() or [""])[-1])) + if rc != 0: + jlog(job, " ! 配置语法不过,请立刻回滚") + wtest = ("[ -w {d} ] && touch {d}/.wtest && mv {d}/.wtest /tmp/.ipass-wtest " + "&& echo WRITABLE || echo NOT_WRITABLE").format(d=CONTAINER_DATA) + rc, out = docker(["exec", "-u", "nobody", name, "sh", "-c", wtest]) + writable = "WRITABLE" in out + jlog(job, " worker(nobody) 数据目录可写:%s" % ("是" if writable else "否 !!")) + if not writable: + jlog(job, " ! 不可写 → 改账号/域名会静默失败,检查 %s 属主" % data_src) + + # ---- 7 数据 + 宿主探活 + jlog(job, "\n7/7 数据与探活") + summ = data_summary(data_src) + jlog(job, " 账号 %s / 域名 %s / 上游 %s" + % (summ.get("users"), summ.get("domains"), summ.get("upstreams"))) + code = http_probe(main_port) + if code: + jlog(job, " https://127.0.0.1:%s 可达(HTTP %s;401=模块正常只是没会话)" + % (main_port, code)) + else: + jlog(job, " ! 宿主 %s 无响应(容器内正常则检查防火墙/端口映射)" % main_port) + + jlog(job, "\n✔ 更新完成") + return {"container": name, "image": image, "main_port": main_port, + "data_dir": data_src, "backup": job.get("backup"), + "rollback_tag": job.get("rollback_tag"), "probe": code, + "data": summ} + + +def op_rollback(job, p): + tag = p.get("tag") + if not tag: + rc, out = docker(["images", "--format", + "{{.Repository}}:{{.Tag}}\t{{.CreatedAt}}"]) + cands = [] + for line in out.splitlines(): + parts = line.split("\t") + if len(parts) == 2 and "rollback-" in parts[0]: + cands.append(parts) + if not cands: + raise RuntimeError("没有 rollback-* 镜像可回滚") + cands.sort(key=lambda x: x[1], reverse=True) + tag = cands[0][0] + jlog(job, "自动选中最近的回滚镜像:%s" % tag) + if not image_exists(tag): + raise RuntimeError("回滚镜像不存在:%s" % tag) + jlog(job, "回滚到 %s\n" % tag) + params = {"image": tag, "skip_pull": True} + for k in ("name", "data_dir", "host_port"): + if p.get(k): + params[k] = p[k] + return op_update(job, params) + + +# ------------------------------------------------------------------ 配置摘要(dry-run) + +def build_check(name=None, data_dir=None, host_port=None): + cname = name or detect_container(None) + if not cname: + return {"ok": False, "error": "未发现候选容器", + "containers": relevant_containers(), + "docker": DOCKER} + cfg = inspect_one(cname) + if cfg is None: + return {"ok": False, "error": "容器不存在:%s" % cname} + data_src, extra = extract_mounts(cfg) + if data_dir: + data_src = os.path.expanduser(data_dir) + port_args, main = extract_ports(cfg, host_port) + return { + "ok": True, + "container": cname, + "running": (cfg.get("State") or {}).get("Status") == "running", + "image": (cfg.get("Config") or {}).get("Image"), + "ports": port_args, + "main_port": main, + "data_dir": data_src, + "extra_mounts": extra, + "network": extract_net(cfg), + "restart": extract_restart(cfg), + "default_image": DEFAULT_IMAGE, + } + + +def build_status(name=None): + cname = name or detect_container(None) + if not cname: + return {"ok": False, "error": "未发现候选容器"} + cfg = inspect_one(cname) + if cfg is None: + return {"ok": False, "error": "容器不存在:%s" % cname} + st = cfg.get("State") or {} + data_src, _ = extract_mounts(cfg) + _pa, main = extract_ports(cfg) + image = (cfg.get("Config") or {}).get("Image") + return { + "ok": True, + "service": SERVICE, "version": VERSION, + "container": cname, + "exists": True, + "running": st.get("Status") == "running", + "state": st.get("Status"), + "started_at": st.get("StartedAt"), + "image": image, + "image_id": (cfg.get("Image") or "")[:19], + "digest": image_repo_digest(image) if image else None, + "main_port": main, + "data_dir": data_src, + "data": data_summary(data_src), + "probe": {"code": http_probe(main), "url": + "https://127.0.0.1:%s/api/admin/users" % main}, + "other_containers": relevant_containers(cname), + } + + +# ------------------------------------------------------------------ HTTP 层 + +BACK = {"quiet": False, "name": None, "data_dir": None, "token": ""} + + +class Handler(BaseHTTPRequestHandler): + server_version = "%s/%s" % (SERVICE, VERSION) + protocol_version = "HTTP/1.1" + + # -------- 基础设施 + def log_message(self, fmt, *a): # noqa: A003 + if not BACK["quiet"]: + sys.stderr.write("[http] %s - %s\n" % (self.address_string(), fmt % a)) + + def _send(self, code, payload): + body = json.dumps(payload, ensure_ascii=False, indent=2).encode("utf-8") + self.send_response(code) + self.send_header("Content-Type", "application/json; charset=utf-8") + self.send_header("Content-Length", str(len(body))) + self.end_headers() + self.wfile.write(body) + + def _auth(self): + if self.path.split("?")[0] == "/health": + return True + got = self.headers.get("Authorization") or "" + if got.lower().startswith("bearer "): + got = got[7:].strip() + if not got: + got = self.headers.get("X-Auth-Token") or "" + return bool(BACK["token"]) and hmac.compare_digest(got, BACK["token"]) + + def _read_body(self): + """读请求体。 + + **鉴权失败时也必须读掉**:HTTP/1.1 是长连接,body 留在 socket 里会被 + 当成下一个请求的请求行,导致响应串包。 + """ + n = int(self.headers.get("Content-Length") or 0) + if n <= 0: + return {} + if n > (1 << 20): + return {"__oversize__": n} + try: + return json.loads(self.rfile.read(n).decode("utf-8")) or {} + except Exception: # noqa: BLE001 + return {} + + def _qs(self): + return parse_qs(urlparse(self.path).query) + + # -------- 路由 + def do_GET(self): # noqa: N802 + self._dispatch("GET") + + def do_POST(self): # noqa: N802 + self._dispatch("POST") + + def _dispatch(self, method): + path = urlparse(self.path).path.rstrip("/") or "/" + self._payload = self._read_body() + if not self._auth(): + return self._send(401, {"error": "unauthorized", + "hint": "Authorization: Bearer "}) + try: + if method == "GET": + return self._get(path) + return self._post(path) + except Exception as e: # noqa: BLE001 + return self._send(500, {"error": str(e)}) + + def _get(self, path): + qs = self._qs() + if path == "/health": + return self._send(200, {"ok": True, "service": SERVICE, + "version": VERSION, "time": now_ts()}) + if path == "/": + return self._send(200, { + "service": SERVICE, "version": VERSION, "docker": DOCKER, + "container": detect_container(BACK["name"]), + "default_image": DEFAULT_IMAGE, + "endpoints": [ + "GET /health", "GET /check", "GET /status", + "GET /containers", "GET /logs?tail=200", + "GET /data?file=users|domains|upstreams", + "GET /jobs?limit=5", "GET /jobs/?offset=N", + "POST /pull {image}", + "POST /update {image,skip_pull,name,data_dir,host_port}", + "POST /rollback {tag?}", "POST /restart", + ], + }) + if path == "/check": + return self._send(200, build_check(BACK["name"], BACK["data_dir"], + None)) + if path == "/status": + return self._send(200, build_status(BACK["name"])) + if path == "/containers": + return self._send(200, {"containers": [ + {"name": n, "image": i, "status": s} + for n, i, s in list_containers()]}) + if path == "/logs": + name = BACK["name"] or detect_container(None) + if not name: + return self._send(404, {"error": "未发现容器"}) + tail = (qs.get("tail") or ["200"])[0] + if not str(tail).isdigit(): + tail = "200" + rc, out = docker(["logs", "--tail", str(tail), name], timeout=60) + return self._send(200, {"container": name, "rc": rc, + "lines": len(out.splitlines()), "log": out}) + if path == "/data": + which = (qs.get("file") or ["users"])[0] + data_dir = BACK["data_dir"] + if not data_dir: + cname = BACK["name"] or detect_container(None) + cfg = inspect_one(cname) if cname else None + if cfg: + data_dir, _ = extract_mounts(cfg) + if not data_dir: + return self._send(404, {"error": "未知数据目录"}) + view = data_view(data_dir, which) + if view is None: + return self._send(404, {"error": "读取失败或文件不存在:%s" % which}) + return self._send(200, {"file": which, "dir": data_dir, "data": view}) + if path == "/jobs": + limit = int((qs.get("limit") or ["5"])[0]) + with JOBS_LOCK: + ids = list(reversed(JOBS_ORDER))[:limit] + return self._send(200, {"jobs": [ + {"id": i, "kind": JOBS[i]["kind"], "state": JOBS[i]["state"], + "created": JOBS[i]["created"], "finished": JOBS[i]["finished"]} + for i in ids]}) + if path.startswith("/jobs/"): + jid = path.split("/", 2)[2] + with JOBS_LOCK: + job = JOBS.get(jid) + if not job: + return self._send(404, {"error": "任务不存在:%s" % jid}) + off = int((qs.get("offset") or ["0"])[0]) + lines = job["log"][off:] + return self._send(200, { + "id": jid, "kind": job["kind"], "state": job["state"], + "rc": job["rc"], "created": job["created"], + "finished": job["finished"], "next_offset": len(job["log"]), + "params": job["params"], "result": job.get("result"), + "container": job.get("container"), + "plan": job.get("plan"), + "log": "\n".join(lines)}) + return self._send(404, {"error": "未知端点:%s" % path}) + + def _post(self, path): + p = self._payload + if path == "/pull": + job, err = start_job("pull", op_pull, p) + return self._send(202 if job else 409, + {"job": job["id"]} if job else {"error": err}) + if path == "/update": + p.setdefault("name", BACK["name"]) + p.setdefault("data_dir", BACK["data_dir"]) + job, err = start_job("update", op_update, p) + return self._send(202 if job else 409, + {"job": job["id"]} if job else {"error": err}) + if path == "/rollback": + p.setdefault("name", BACK["name"]) + p.setdefault("data_dir", BACK["data_dir"]) + job, err = start_job("rollback", op_rollback, p) + return self._send(202 if job else 409, + {"job": job["id"]} if job else {"error": err}) + if path == "/restart": + name = p.get("name") or BACK["name"] or detect_container(None) + if not name: + return self._send(404, {"error": "未发现容器"}) + rc, out = docker(["restart", name], timeout=120) + code = http_probe(build_check(name).get("main_port")) + return self._send(200 if rc == 0 else 500, + {"container": name, "rc": rc, "log": out.strip(), + "probe": code}) + return self._send(404, {"error": "未知端点:%s" % path}) + + +class ThreadingServer(ThreadingMixIn, HTTPServer): + daemon_threads = True + allow_reuse_address = True + + +# ------------------------------------------------------------------ token + +def load_token(cli_token): + if cli_token: + return cli_token + env = os.environ.get("IPASS_AGENT_TOKEN") + if env: + return env + path = os.path.join(os.path.expanduser("~"), ".ipass-agent-token") + if os.path.exists(path): + try: + with open(path, "r", encoding="utf-8") as f: + t = f.read().strip() + if t: + return t + except Exception: # noqa: BLE001 + pass + t = "".join(random.choice(string.ascii_letters + string.digits) for _ in range(40)) + try: + with open(path, "w", encoding="utf-8") as f: + f.write(t + "\n") + os.chmod(path, 0o600) + except Exception: # noqa: BLE001 + pass + return t + + +# ------------------------------------------------------------------ main + +def daemonize(logfile, pidfile): + if os.fork() > 0: + os._exit(0) + os.setsid() + if os.fork() > 0: + os._exit(0) + os.chdir("/") + fd = os.open(logfile, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644) + os.dup2(fd, 1) + os.dup2(fd, 2) + os.dup2(os.open(os.devnull, os.O_RDONLY), 0) + try: + with open(pidfile, "w") as f: + f.write(str(os.getpid()) + "\n") + except Exception: # noqa: BLE001 + pass + + +def do_stop(pidfile): + if not os.path.exists(pidfile): + print("没有 pid 文件 %s,服务可能没在跑" % pidfile) + return 1 + with open(pidfile) as f: + pid = int((f.read().strip() or "0")) + try: + os.kill(pid, 15) + print("已发送 SIGTERM 给 pid %s" % pid) + except ProcessLookupError: + print("pid %s 已不存在" % pid) + try: + os.unlink(pidfile) + except Exception: # noqa: BLE001 + pass + return 0 + + +def main(): + ap = argparse.ArgumentParser(description="iPass 容器远程更新控制面") + ap.add_argument("--port", type=int, default=DEFAULT_PORT) + ap.add_argument("--bind", default="0.0.0.0") + ap.add_argument("--name", help="容器名(缺省自动探测)") + ap.add_argument("--data-dir", help="数据目录(缺省从容器挂载读)") + ap.add_argument("--image", help="默认更新目标镜像") + ap.add_argument("--token", help="访问令牌(缺省用环境变量/~/.ipass-agent-token)") + ap.add_argument("--check", action="store_true", help="只探测并打印结果,不起服务") + ap.add_argument("--bg", action="store_true", help="后台运行") + ap.add_argument("--stop", action="store_true", help="停止后台服务") + ap.add_argument("--quiet", action="store_true", help="不打印访问日志") + a = ap.parse_args() + + if a.image: + globals()["DEFAULT_IMAGE"] = a.image + BACK["quiet"] = a.quiet + BACK["name"] = a.name + BACK["data_dir"] = a.data_dir + BACK["token"] = load_token(a.token) + + pidfile = os.path.join(os.path.expanduser("~"), "ipass-agent.pid") + logfile = os.path.join(os.path.expanduser("~"), "ipass-agent.log") + + if a.stop: + return do_stop(pidfile) + + if a.check: + print(json.dumps(build_check(a.name, a.data_dir, None), + ensure_ascii=False, indent=2)) + return 0 + + if a.bg: + if os.path.exists(pidfile): + try: + with open(pidfile) as f: + pid = int(f.read().strip()) + os.kill(pid, 0) + print("已在运行(pid %s)。先 --stop 再启动。" % pid) + return 1 + except Exception: # noqa: BLE001 + pass + daemonize(logfile, pidfile) + BACK["quiet"] = True + print("[%s] %s %s 启动于 %s:%s" % (time.strftime("%F %T"), SERVICE, + VERSION, a.bind, a.port), flush=True) + print("token: %s" % BACK["token"], flush=True) + + srv = ThreadingServer((a.bind, a.port), Handler) + cname = detect_container(a.name) + if not a.bg: + print("%s %s" % (SERVICE, VERSION)) + print(" 监听 %s:%s" % (a.bind, a.port)) + print(" token %s" % BACK["token"]) + print(" 容器 %s" % (cname or "(未发现,可用 --name 指定)")) + print(" 镜像 %s" % DEFAULT_IMAGE) + print(" 日志 %s" % (logfile if a.bg else "(stdout)")) + try: + srv.serve_forever() + except KeyboardInterrupt: + print("\n退出") + finally: + srv.server_close() + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/readme.md b/readme.md index 7ef6959..5b1b949 100755 --- a/readme.md +++ b/readme.md @@ -547,6 +547,63 @@ bash update-ipass.sh --bg # 后台更新(日志落 ~/ipass-update-<时 - 旧容器若由 compose 创建,脚本会提示「已改用 docker run 接管」,想继续用 compose 请改用 `docker compose -f 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 首次启动随机生成并写入 + `~/.ipass-agent-token`(权限 600),也可用 `--token` 或环境变量 `IPASS_AGENT_TOKEN` 指定。 +- 端口/挂载/网络/env/重启策略**全部从旧容器 `docker inspect` 复刻**,不写死任何参数; + 自定义 env 会保留,Docker 自带的(PATH / NGINX_VERSION…)不会照抄。 +- 变更类接口是**异步任务**:立刻返回 `{"job":""}`,用 `GET /jobs/?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/?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 ' + +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/ # 拉执行日志(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/?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` 静态配置,**停止态容器也能正确识别**;