xunx · 多用户复用服务¶

xunx 用同一个镜像为每个用户维护一个常驻容器，再用单个网关进程按 URL 前缀转发。用户看到的是 http://网关:18960/alice/chat/，容器内部跑的仍是 xuns --base-path /alice。

xunx user-add alice
xunx serve --host 0.0.0.0 --port 18960

概念¶

概念	说明
用户库	SQLite，路径 `{XUN_HOME}/x/xunx.db`，字段 `name / token / generation`
令牌	每个用户一个随机令牌（`secrets.token_urlsafe(24)`），同时作为其容器的 `xuns --token`
URL 前缀	固定为 `/{username}`，容器据此生成正确的相对链接
容器名	`xunx-<实例ID前8位>-<用户名>`，实例 ID 为用户库路径的哈希
端口	在 `--port-range` 内随机挑选空闲端口，仅绑定 `127.0.0.1`（宿主端口 = 容器端口）
代次 generation	每次 `upgrade` 递增；对账时发现代次过期就重建容器
对账 reconcile	每 `--interval` 秒一次：清理越界容器、接管已有容器、补起缺失容器、清理孤儿容器

子命令¶

user-adduser-del / user-listupgradeserve

xunx user-add alice

用户名只允许字母、数字、_、-；重复添加报错。输出用户与令牌表格，令牌即访问密码。

xunx user-del alice      # 删除用户；其容器在下次对账时被清理
xunx user-list           # 列出 USER / TOKEN / BASE PATH

xunx upgrade alice       # 或 xunx upgrade --all

只递增数据库里的 generation 并提示「Queued upgrade」，真正的重建发生在下一次 serve 对账时；容器内数据（工作区、已保存会话）会随之丢弃。

参数	默认	说明
`--host`	`0.0.0.0`	网关监听地址
`--port`	`18960`	网关端口（会从可用端口池里排除）
`--port-range`	`17960-18959`	容器可用端口区间，格式 `START-END`
`--image`	`xun`	使用的镜像
`--env`	空	与 `xunc --env` 同义：`NAME=VALUE` 赋值或通配符转发；`XUN_`/`_XUN_` 总是转发
`--interval`	`5`	对账间隔秒数（帮助中隐藏），必须大于 0

请求如何被转发¶

flowchart LR
  U["浏览器<br/>/alice/chat/"] --> G["xunx 网关<br/>:18960"]
  G --> R["用户库<br/>用户名与令牌"]
  G --> C["容器内 xuns<br/>--base-path /alice"]
  C -.->|"相对链接自带 /alice 前缀"| G

路径原样转发（含 /alice 前缀与查询串），不做改写：容器内的 xuns 已经通过 --base-path 知道自己在 /alice 下。
用户名不存在 → 404 User not found；上游不可用 → 502 Upstream unavailable。
支持 WebSocket（事件流），双泵转发，心跳 20 秒；逐跳头部（connection、transfer-encoding、upgrade 等）双向剥离。
每个用户的 URL 由该用户容器自己打印，形态为 http://<网关>:18960/alice/chat/?session=/&token=<令牌>。

持久化与对账¶

serve 重启后不会重建容器：对账时先按容器名接管正在运行的容器（读取其发布端口与标签），只有令牌或代次过期时才重建；用户被删除、容器已退出、或不属于本实例的容器会被停止/清理（首次对账额外清理本实例遗留的孤儿容器）。容器日志会被转发到 serve 的 stderr，行首带容器名。

xunx user-list
xunx upgrade --all        # 镜像更新后，让所有用户在下次对账时用新镜像重建

对外发布

网关监听 0.0.0.0 时，令牌是唯一凭据；生产环境建议置于 HTTPS 反向代理之后，并透传 X-Forwarded-Proto，这样登录 Cookie 才会带上 Secure。