一个订阅中心管理多台机器。每位朋友各有稳定订阅 URL 和独立 UUID;同一个 Mihomo/Clash Meta 或 Quantumult X 订阅包含发布的就绪节点与服务端两跳线路。国内、局域网、Apple/iCloud 直连,其余走 VPS 节点组。没有就绪节点时,默认代理流量被拒绝,避免意外直连。
已安装且登记了节点的中心,可以另外添加独立订阅别名:./proxyctl domain add sub.example.com。它保留原控制/节点地址和所有身份,单独管理别名 HTTPS;菜单 16–19 可查看、添加、移除和恢复。使用方式、DNS/端口要求、已有手工别名迁移及事务回滚见 订阅域名管理。原安装器的域名/HTTPS 安装功能继续按下面流程使用。
支持 Linux、本机 rootful Docker Engine、Compose ≥ 2.24.4、Bash 和 GNU coreutils(timeout/sha256sum)。不支持 Docker Desktop 的端口预检、远程 Docker 或 rootless Docker。独立安装不需要宿主 Python/git;可选的安装后订阅域名管理需要宿主 Python 3.9+(包括栈内 Caddy 方式),自动集成宿主 Caddy 另需 Linux root、systemd 和 ss。
docker run --pull=always --rm ghcr.io/silaswei-io/proxy-stack:v1.0.0 installer | bash向导逐行选择「中心 + 本机节点」(默认)、「仅订阅中心」或「加入已有中心」。地址默认探测到的公网 IP,名称默认 hostname,均可回车接受;公共 HTTPS 端口默认选取 20000–59999 的空闲随机端口,也可自行输入。--port 52789 指定端口(1–65535,80 留给 HTTP-01)。安装前及激活前都会重新检查占用;生成的订阅 URL、订阅内的规则资源 URL 和节点连接端点都使用实际所选端口(标准 HTTPS 443 的 URL 可省略端口),重复运行保留已选端口。
安装器在公共 nonce 回环检查前,以及正常安装或 --prepare-only 成功收尾时,都会提示实际所选端口:请在云控制台防火墙/安全组添加入站规则,并在宿主防火墙放行 TCP 80(证书签发/续期)及所选 TCP HTTPS 端口(订阅/代理);使用 NAT 时还需将这两个公网端口映射到本机同号端口。交互安装和交互 --check 会暂停,输入 y 确认已放行后才检查;失败可在当前端口调整规则,输入 r 重试一次,无需重新随机选端口。其他输入取消,仍保留原安装和宿主配置。--non-interactive 只提示、不等待、不自动重试,请提前放行显式 --port,或根据失败提示配置后重跑。--prepare-only 不做连通性检查,也不要求此确认;无变更的准备重跑仍会提醒。工具不会自动开放防火墙。后续涉及宿主路由或受管重配的计划确认仍单独保留。
普通安装和 --check 会在写入安装/宿主配置前,用临时 nonce HTTP 监听器及另一个 bridge 容器,对所选空闲 HTTPS 端口做公共地址回环检查(启动命令最多 10 秒、探测命令最多 15 秒、清理命令最多 5 秒)。两个容器还各自以 Linux SIGALRM 强制截止:监听器 30 秒、客户端 12 秒,覆盖慢速请求头、DNS 和慢速读取;请求空闲超时仍为 2 秒,退出/中断时仍清理两个容器。显式和随机端口都检查;失败提示检查防火墙、云安全组、NAT/回环支持,不搜索其他可穿透防火墙的端口。回环通过不证明真正外部入站可达,部分网络也可能只因不支持 NAT 回环而失败。精确确认已有受管 Caddy 占用该绑定时跳过临时监听,后续 HTTPS 完成验证仍必需;--prepare-only 跳过回环。
栈内固定 Caddy 2.11.4 在所选端口终结 TLS,仅使用 Let’s Encrypt HTTP-01。公网 80 空闲时直接发布栈内 80;若被受支持的 stock systemd Caddy ≥ 2.6 占用,工具自动验证完整候选配置,添加仅此地址 ACME challenge 路径到已检查的随机回环端口,再转入栈内 80。宿主 443、Caddy 二进制、unit 及原有路由/import 原文保持不变,不需要升级宿主 Caddy。公共 IP 使用 shortlived profile 和栈内 default_sni。
自动适配要求宿主 root 所有的普通配置/程序、可确认的监听 PID/启动参数、stock 模块、标准本机 admin/reload,且运行配置与磁盘一致。自定义模块、未知监听者、目标地址已有站点/catch-all、动态/不安全配置等会在预检失败,不写入安装目录、不修改宿主服务。域名的全部 A/AAAA 必须能由本机 IPv4/IPv6 出口证明;额外多地址/NAT 无法证明时会明确拒绝。工具不更改 DNS、防火墙或云平台设置;公网需允许 80 和所选 HTTPS 端口,域名 CAA 需允许签发。
先看完整计划,再安装;--check(同 --plan)可拉取/验证镜像、创建私有临时计划和短暂端口探测容器,但不写入安装目录、启动栈或重载宿主:
docker run --rm ghcr.io/silaswei-io/proxy-stack:v1.0.0 installer | bash -s -- \
--check --domain YOUR_PUBLIC_IP --port 52789 --directory /opt/proxy-stack
# 无交互:--manage-host-caddy 仅授权计划中的宿主 HTTP-01 路由事务。
docker run --rm ghcr.io/silaswei-io/proxy-stack:v1.0.0 installer | bash -s -- \
--non-interactive --domain YOUR_PUBLIC_IP --port 52789 \
--manage-host-caddy --directory /opt/proxy-stack交互模式在宿主路由或受管重配前只确认一次计划;无交互自动集成须显式 --manage-host-caddy。可选 --name 'My VPS'、--role hub-only;原始 IPv6 不加方括号。镜像拉取、候选验证和 HTTPS 等待均有上限并显示简短进度,常规 Docker 输出写入提示的私有日志(0600)。加入码、UUID 和私密订阅 URL 不写日志。
安装使用持久事务记录:修改前备份配置和身份,原子替换宿主配置并 native 验证/重载;服务启动后最多 120 秒验证公共 HTTPS。中心需返回自身订阅的确切内容与正确 TLS;选了本机节点还需当前 generation 的有效运行回执,节点模式还检查自身公共 WSS 和近期本机运行/同步。失败恢复宿主原配置、受管原模板/状态和原本运行的服务;新安装只清理自己的 Compose 资源,并把私有状态留在事务备份。没有 HTTPS 或有效节点回执时不会显示可用订阅链接。
等待期间约每 10 秒报告已用时间和安全分类原因;最终区分超时、连接、TLS、HTTP 响应、内容、本机状态及节点运行同步问题,不输出原始 URL/异常。回滚移除容器前,把本次 Caddy 的有限诊断保存到事务目录的 caddy-diagnostics.log(0600),不直接显示原始日志。
仅中心模式可以在 HTTPS 已验证、零节点时完成安装,收尾明确「等待就绪节点回执」;在中心菜单生成限时加入码即可继续:
/opt/proxy-stack/proxyctl node code加入码有效 10 分钟、只用一次。在其他服务器运行相同向导,选「加入已有中心」并粘贴隐藏输入;无交互使用 --role node --join-code-file /secure/join-code。秘密只经 stdin 传入,不能放进命令参数。新节点安装失败会撤销其独立登记;中心暂时不可达时保留这份私有凭据及事务锁,恢复后重试撤销,不遗留一个被误报成功的节点。
相同 v1.0.0 的受管安装可直接重跑:保持 UUID/token/WS 路径,显式 --domain/--name/--port 会预检并事务重配、刷新随包模板和再生成运行配置。已有的 pending MODE=existing-caddy 默认重试为栈内 HTTPS,未指定新端口时选择空闲随机端口。角色不自动切换;中心已有远程节点或节点已有登记时,不能自动改变其公共控制/节点地址,预检会保留原状态并拒绝。正常无变更重跑不重建原容器;失败不停止原本运行的容器。
普通重跑会发现未完成事务,先安全恢复;也可只恢复,不继续安装:
docker run --rm ghcr.io/silaswei-io/proxy-stack:v1.0.0 installer | bash -s -- \
--directory /opt/proxy-stack --recover活动安装锁不会被抢占;--check 发现未完成事务仅报告恢复命令。若检测到外部并发改动或暂时无法撤销登记,保留锁、备份和私有日志,恢复可再次执行。事务记录目录应保留到确认完成;不会删除原用户私有状态。
当前安装器可恢复 611082f 版本留下的旧事务:仅精确识别已知旧 helper 哈希后替换为当前 helper,并保留 host_setup.611082f.original.py 原始字节;未知 helper 或备份冲突会拒绝执行。服务命令只比较稳定的 executable、argv 和 ignore_errors,兼容旧 journal 原始字符串;重载时间/PID 变化不再误报外部 unit 改动,真实 unit、程序、命令、import 或运行配置漂移仍拒绝覆盖。
--prepare-only 初始化但不启动栈、不探测公共就绪、不输出私密链接;它不能重配正在运行的安装。专家可显式 --mode existing-caddy --prepare-only 生成 data/runtime/host-caddy.snippet,保留片段 TLS/global 要求;这是手动集成的高级入口,正常安装使用自动 HTTP-01 流程。
/opt/proxy-stack/proxyctl finish # 单次最多约 4 秒;待完成返回 1,就绪返回 0
/opt/proxy-stack/proxyctl finish --wait 120
/opt/proxy-stack/proxyctl menu # 重试完成检查;我的订阅查看 Quantumult X 等链接finish 仅在公共 HTTPS 返回本中心当前订阅、且该订阅至少有一条已发布的就绪可选线路时,显示 Mihomo 和 Quantumult X 的五个实际私密 URL(与菜单「我的订阅」一致)。直连线路需要对应节点已确认当前配置且租约有效,两跳线路需要入口和出口同时满足;隐藏的直连不计数。检查始终验证 TLS,不跟随重定向、不使用环境代理,网络等待不持有状态锁。节点检查自身 HTTPS/WSS 和运行/同步,不检查订阅。它不代表真实客户端导入或代理出站验收,也不能保证云防火墙、NAT、公共 ACME 签发和持续续期。
「节点」是按原有三种角色安装/加入的物理服务器;「线路」是在中心命名的一条入口 → 出口路径。美国服务器照常选择「加入已有中心」,不需要新角色或出口转发程序。例:国内客户端 → 首尔入口 → 美国出口 → 网站;入口必须能访问美国节点原有的 HTTPS/WSS 地址和端口,出口证书必须有效。只需升级中心与入口;若首尔是同一套「中心 + 本机节点」安装,升级这一套即可,美国普通出口无需升级。仅作为出口的旧节点可保留原运行时,仍收到原来的四字段控制对象。
在中心安装目录操作(仅中心角色没有 local 节点,应指定已加入的入口 ID):
./proxyctl node list
./proxyctl chain add usa --name '美国经首尔' --entry local --exit USA_NODE_ID
./proxyctl chain list
./proxyctl node publish USA_NODE_ID off # 隐藏美国直连,不禁用出口或撤销用户
./proxyctl node publish USA_NODE_ID on # 恢复直连发布
./proxyctl chain remove usa中心的中文菜单提供查看、添加、移除线路和节点直连显示/隐藏。已有安装的 upgrade 保留磁盘包装器,不会自动增加菜单;按原安装参数重跑当前安装器可刷新模板并保留身份。未刷新包装器时,命令可直接经 docker compose run --rm -T --no-deps manager chain ... 转发;旧包装器的 node publish ID off 也可直接转发。升级入口镜像后检查其 node list 回执;仅重跑无变更安装器不会重建运行中的容器。安装事务行为保持不变。
刷新原有订阅后,Mihomo 和 Quantumult X 同时显示「首尔直连」与「美国经首尔」。两个选项都连接首尔原有的单一 WS 路径和 TLS 端点,无需客户端链式代理功能,不新增端口或 Caddy 模板,也无需为线路增删重载 Caddy。隐藏直连仅影响生成的订阅,不撤销已缓存的直连凭据、连接或退出节点资格。原有订阅 URL 和普通 UUID 保持稳定;Quantumult X 原生 iOS 导入/实机连接仍未验证。
控制数据只给入口增加它所需的随机线路 ID 和出口地址、端口、WS 路径,复用原 users 列表在入口派生身份,避免按用户重复下发拓扑;不下发其他节点、订阅 token 或 peer token。每位用户、每条线路使用独立派生入口 UUID;入口按该身份选择同一用户在出口的普通 UUID。线路重建会获得新的随机内部 ID,已移除线路的凭据不会复活。线路只在入口、出口均启用、租约有效且确认各自当前 desired generation 时发布。离线、pending、移除和 detach 均使线路不可发布;入口仍运行的旧配置也只能访问指定出口,出口失败不会回退到入口直出。撤销或移除须等待入口应用新配置;离线入口最迟在既有租约到期停止。入口配置更新沿用现有运行时重启 Xray 的机制,会中断入口现有连接。已缓存的客户端订阅不会被远程改写,需要刷新;连接失败不会自动换线路,选用客户端自动切换组可能按客户端配置另选其他线路。
第一版仅支持两个不同物理节点组成的两跳,不可引用其他线路;即使出口同时是其他线路的入口,出口接收到的普通 UUID 也始终直出。最多 32 条线路、128 位用户,沿用现有节点上限;同入口/出口组合不能重复。线路标识为小写字母开头的 1–32 位英文/数字/_/-,显示名沿用节点名规则(1–80 字,不含逗号等配置字符,不与节点、其他线路或保留策略名冲突)。移除的物理节点不会被线路自动替换;先移除旧线路、正常加入新节点,再创建新线路。
./proxyctl menu # 中文菜单;终端中无参数也可打开
./proxyctl finish # 检查完成条件;成功才显示 Mihomo / Quantumult X 链接
./proxyctl links --labelled # 显式披露 owner 五个私密 URL,不检查就绪
./proxyctl user add alice # 独立 UUID/token,下发所有节点
./proxyctl links --user alice
./proxyctl user revoke alice # 立即移除订阅,等待各节点应用回执
./proxyctl node list # ID、desired、acknowledged、active、同步状态
./proxyctl node code # 显式显示一次性加入码
./proxyctl node remove NODE_ID # 立即使节点控制凭据失效;本机 ID 为 local
./proxyctl node join # 节点读入加入码;隐藏终端输入,也接受 stdin
./proxyctl detach # 节点停止参与中心;中心不可达时本地仍会解除
./proxyctl status
./proxyctl verify # 中心真实 HTTPS 资源哈希、MIME、GET/HEAD 检查
./proxyctl update-rules
./proxyctl upgrade # 拉取 v1.0.0,重建原本运行的服务;保留身份与模板,迁移旧官方镜像默认
./proxyctl up
./proxyctl down # 保留数据与证书,不接受删除参数订阅使用不带扩展名的私密地址:https://host/<48hex-token>/clash、/<48hex-token>/quantumult-x(完整配置)、/<48hex-token>/quantumult-x/nodes、/<48hex-token>/quantumult-x/rules(受管规则)、/<48hex-token>/quantumult-x/rules-portable(独立规则)。Mihomo 规则资源为 /<48hex-token>/rules/<name>。token 保持原有 48 位十六进制熵;旧 /sub/<token>/clash.yaml、/sub/<token>/qx/... 和规则地址继续可用。Caddy 仅对精确 GET/HEAD 做内部映射,不跳转、不接受查询参数;底层文件和 manifest 路径保持兼容。
Quantumult X 的 quantumult-x 链接应按完整配置文件导入,其中已配置 VPS 策略组、节点和规则资源。保留自己的配置时,将 quantumult-x/nodes 放入 [server_remote],将 quantumult-x/rules-portable 放入 [filter_remote];独立规则仅使用内置 proxy/direct,无需自建 VPS 组,代理节点由客户端选择。原 quantumult-x/rules 及旧 qx/rules.list 保留 direct/VPS,仍供完整配置的自定义 VPS 组使用。两个版本的规则顺序和匹配条件相同;不要设置统一的 force-policy,以免覆盖直连分流。rules/<name> 是 Mihomo 的 YAML payload,不能作为 QX 的 filter_remote;完整配置也不能当节点或规则资源导入,否则会产生格式错误。QX 原生 iOS 导入仍待实机验证。
官方项目与镜像命名空间为 silaswei-io/proxy-stack,公开版本仍为 v1.0.0。旧 ghcr.io/silaswei/proxy-stack:v1.0.0 的受管安装可重跑新安装器或运行新版 proxyctl upgrade,仅迁移官方镜像默认,保留 UUID、token、WS 路径和其他设置。自定义镜像和其他标签需手动迁移。已有安装要启用新订阅路由,请正常重跑新安装器(不用 --prepare-only);proxyctl upgrade 只更新镜像默认与原本运行的服务,保留现有运行配置。安装器的模板更新仍使用原有事务备份/回滚;upgrade 在解析新镜像失败时恢复 .env,服务重建失败时可将 TOOL_IMAGE 恢复为旧官方地址后重试。
节点不生成自己的订阅链接;所有订阅与规则链接均指向中心,节点连接地址使用各节点自己的 IP/域名和 WS 路径。owner 永久保留;朋友标识匹配 [a-z][a-z0-9_-]{0,31}。添加/撤销不会更改其他用户的 UUID/token/URL。用户变更由各节点自动应用,重启该节点的 Xray 会中断其已有连接。
node list 的 synced 表示该节点已校验配置、成功启动 Xray 并回执当前 generation;pending 表示当前授权尚未确认;offline 表示超出租约心跳窗口;removed 表示已禁用。acknowledged 是最后确认版本,active 仅在当前版本就绪且租约有效时显示,否则为 0。不能把撤销后的 pending/offline 称作已应用。
节点默认每 2 秒轮询,中心租约默认 300 秒(LEASE_SECONDS,10–3600)。节点在失联时可暂用最后好配置,租约到期由独立单调时钟看门狗终止 Xray,即使控制请求阻塞也执行。重启节点进程必须重新获取有效配置,不恢复磁盘上的旧租约。移除节点立即拒绝后续控制请求,已离线节点最迟在剩余租约结束停止。关闭/移除中心也受同一限制;需自行删除不再使用的主机 HTTPS 路由。
订阅只发布确认当前授权的节点;新增用户、撤销用户、节点启动/恢复期间可能暂时没有节点,默认代理流量此时 REJECT/reject。显式国内/LAN/Apple/iCloud 规则继续直连。客户端已经缓存的旧订阅不会被远程强制刷新,但节点实际授权仍由独立 UUID 和租约限制。
manager是一次性 CLI;hub提供内部控制 API;xray使用工具镜像内的固定官方 Xray 二进制并监督子进程;updater只处理规则。加入节点上的 hub/updater 进程休眠。- Caddy 只开放四个精确 POST 控制路径
/control/v1/{enroll,poll,ack,detach}和精确订阅资源路径,控制监听器无宿主机端口。仅订阅中心不开放 Xray tunnel。 - 控制客户端始终校验 HTTPS,禁用重定向和环境代理。加入码有 192 位随机秘密,服务端只存摘要;加入后每个节点使用独立秘密。普通 status/日志不输出 UUID、token 或加入码;只有显式 links/code、菜单订阅操作与通过完成检查后的收尾主动显示。
- 节点只取得所需 UUID、自己的 WS 路径、generation 和租约,不取得用户订阅 token、其他节点控制秘密或中心完整状态。
- 所有模型、发布和规则操作共享
flock;原子选择公共 revision。心跳单独保存,只在节点可见性发生变化时重新渲染,不在每次轮询重建大型规则。旧 revision 及时删除,撤销 token 不在旧公共树中残留。 - updater 只读模型,读写 cache/public/locks,完全不挂载 runtime。没有 docker.sock、privileged 或 host networking。Caddy 单独保留低端口绑定 capability,其余容器
cap_drop: ALL。
data/model/state.json 中心用户/节点模型,或节点自身非秘密设置
data/model/peer.json 加入节点自己的私密中心凭据
data/model/heartbeats.json 中心节点最近轮询时间
data/runtime/xray/active.json 监督运行器实际应用的配置
data/runtime/node-status.json 运行器状态;没有用户秘密
data/runtime/caddy/ 本机 Caddy 配置
data/cache/ 最后一次完整规则与刷新状态
data/locks/ 跨进程写入锁
data/public/current 原子指向已校验的发布目录
私有目录 0700、模型与控制凭据文件 0600。订阅和 Xray 配置同样包含秘密;备份应加密并限制访问。不要公开 URL、UUID、token,也不要上传到第三方二维码站。栈内 Caddy 排除请求 access/error 日志,避免泄漏订阅/WS 私密路径。专家手动反代入口也应避免记录这些路径或请求体。
规则源固定为 Loyalsoldier/clash-rules 的 private/apple/icloud/proxy/direct/cncidr/lancidr。首次为 minimal-bootstrap,不代表完整国内分流;updater 成功后 rules=upstream。下载限时限量,拒绝危险 YAML 与异常缩水,失败保留最后好版本。两客户端按首尔基线排序:四个 IP 查询域名代理 → 中心/各节点引导直连 → localhost/.local/.lan → 八条内联私网 IP → private → lancidr → iCloud → Apple → proxy → .cn → direct → cncidr → 默认 VPS。节点和中心地址使用本部署的精确域名或 /32、/128 规则,策略名称保留 VPS。
Mihomo 完整订阅包含首尔基线的 fake-ip、国内 DoH 引导/节点解析和国内/海外 DNS 分流,中心及节点域名优先国内解析;私网 IP 和 lancidr 为 no-resolve,cncidr 保留解析。新完整配置内联关键规则并引用七个源 provider,旧九个资源地址及 classical 格式继续兼容。QX 完整配置内联关键安全规则,受管/独立分流资源保留相同顺序;官方未文档化的 IP no-resolve 和 Mihomo DNS 字段不输出到 QX。QX 的 DNS 行为仍需设备验证。升级时刷新或重新导入完整配置,仅刷新规则资源不会改变旧缓存的 DNS/顺序。各订阅的导入方式和能力边界见 CLIENTS.md。
只提供 TCP VLESS/WSS/TLS,不启用 UDP 或 IPv6 DNS。固定 Xray 默认阻止私有地址代理出站。没有面板、Reality、计费或自动公网运维。本次是全新 v1.0.0,不提供旧版本状态/模板迁移。
高级源码使用:复制 .env.example 为 .env,设置 DOMAIN、ROLE、LOCAL_NODE,运行 ./proxyctl init 与 ./proxyctl up。源码安装需要仓库读取权限;部署只使用 GHCR 镜像则无需 git。新 v1.0.0 的重复 init 保留身份,部署设置不允许静默更改。
docker build -t proxy-stack-tool:v1.0.0 -f manager/Dockerfile .
docker run --rm --network none --entrypoint python -v "$PWD/tests:/tests:ro" \
proxy-stack-tool:v1.0.0 -m unittest discover -s /tests -v
DOMAIN=proxy.example.com docker compose config --quiet
DOMAIN=proxy.example.com docker compose -f compose.yaml -f compose.external.yaml config --quiet
# 快速 native 预检:真实 Debian Caddy 2.6.2、固定栈 Caddy 和导出安装器 --check。
python3 tests/integration/preflight.py
# 首尔路由/DNS 与旧 classical 缓存:首次自动拉取固定 Mihomo 镜像,随后原生离线解析。
python3 tests/integration/routing.py
# 完整集成(内部也会运行上述 native 预检);Linux rootful Docker 需 sudo。
sudo python3 tests/integration/run.pynative 预检用私有配置和回环随机端口;macOS 上的测试适配器仅替换 Linux 宿主判定、缓存镜像和探测绑定,不证明 Docker Desktop 的端口占用能力。完整集成测试仅使用独立临时容器/网络、回环随机高端口与显式测试 CA。覆盖实际 Mihomo 经两台受监督 Xray 的 HTTPS/WSS/VLESS 出站、各节点独立用户同步与撤销、失联/阻塞期间租约停止、失败启动不回执、移除、稳定中心 URL;保留单节点和 IPv4/IPv6 SAN、无 SNI、错误证书拒绝、规则隔离测试。测试仅在独立临时配置中放行模拟 origin 的 IP:8000,不改变生产配置。Linux 需 sudo,以保持 root 所有的私有挂载和 cap_drop ALL;不能用放宽私有目录权限替代。
发布工作流在 main push 或 main 手动触发,测试后构建 amd64/arm64 immutable sha-<revision> 镜像;发布串行执行,确认仍为当前 main 才更新唯一用户入口 ghcr.io/silaswei-io/proxy-stack:v1.0.0。历史标签保留。
Quantumult X 原生 iOS 导入、公共 ACME 签发/续期和真实 VPS/运营商网络尚未在本地环境验证。 见 客户端验收 与 验证记录。代码 MIT;下载规则遵循上游 GPL-3.0,见 第三方归属。