共享 wgcf / WireGuard 运维工具¶

适用于 v1.31.83 及后续版本。面板提供内置的轻量 WARP 出口管理；保留的 tools/wgcf-warp 是面板外的可选运维工具：一个共享容器运行多个 userspace wireproxy 进程，每份配置使用独立 WARP 注册材料和 SOCKS5 监听。面板通过已有 wireguard_warp 代理 API 检测出口并逐账号绑定。新建出口统一使用轻量运行器，旧 Docker WARP 管理及路由支持已移除。仍使用旧容器的安装应先完成下文迁移，再升级；已经升级的安装可按“已升级后的补迁移”恢复账号路由。内置页面和独立工具都不能将模拟测试解释为可承载 100 个账号的证明。

面板内置管理（v1.31.83）¶

升级到 v1.31.83 的 Linux Docker 镜像后，在“代理管理”页点击“一键创建 WARP”创建出口。出口名称可填写，也可留空由系统自动命名；该入口会使用已接受的 Cloudflare WARP 条款直接提交。注册材料、私钥和 SOCKS 密码仅存放在面板的持久卷 wgcf-warp/，页面和 API 都不会显示它们。

首次启用此功能必须拉取并重新创建新版 Docker 镜像。旧镜像仅执行面板内“一键更新” 不会安装 Python、wgcf 和 wireproxy，页面会提示运行环境缺少依赖。

轻量出口直接显示在下方统一代理列表，不再另设档案列表。创建中或失败、尚未生成代理编号的档案也会占一行；生成代理记录后仍是同一出口，不重复展示。

创建在后台执行，刷新页面后仍显示同一请求；失败时使用“恢复”重试，不能重新填写并创建第二份档案。上游注册结果不明确时，系统保留材料并拒绝自动重复注册。
列表行内提供启动、停止、恢复、检测和单账号绑定，并分别显示期望启停、进程监听和 WARP 检测。监听不等于 WARP 可用；只有检测显示成功后才可选择一个已存在的账号绑定。
内置出口支持专属使用，也支持通过已有代理、批量绑定或全局代理显式共享；登录、导入同样可选。共享账号使用同一出口，自动空闲池仍只独占领取无账号、无全局占用的出口。未完成首次连接的临时出口不能共享；绑定仍使用账号当前代理和全局模式的并发快照，避免覆盖人工改动。
停止或删除前，先将全部绑定账号迁往其它路由、解除启用的全局引用并等待临时操作结束；系统不会静默让账号降级直连。轻量代理可以勾选、多选、批量分类和删除，单行也有删除入口。未生成代理编号的档案也可勾选删除，分类需要代理记录已生成；创建任务仍占用时需等待结束。
删除操作先确认进程已停止，再清理本地代理和档案材料，不保证注销 Cloudflare 远端设备。失败保留可重试状态；批量删除逐项返回结果，使用中的项目保留，不影响其它可删除项。
v1.31.82 也可在代理行点击“已绑定账号”直接解绑或换绑。必须明确选择目标代理、全局代理或直连，再确认提交；原出口保留，不自动停止。验收时核对原列表账号消失、新路由及使用数量刷新。若响应超时或报绑定冲突，先刷新核对，避免重复操作。该列表只列显式绑定账号，全局继承使用数另外提示。
恢复失败档案或重新启动时，系统会先确认本地监听，再重新启用对应的受管代理记录并检测；未完成前不会显示为可绑定。

账号登录、导入和账号代理绑定可选择“创建一对一 WARP”，阅读并勾选条款后，每个账号独立创建轻量出口；导入与批量绑定单次最多 10 个。无需 Docker Socket、NET_ADMIN 或独立出口容器。首次 Telegram 连接前必须完成 WARP 联网检测；失败停止未绑定出口并保留材料，不会回退直连。登录重发验证码或重新生成二维码会复用同一出口。

验收记录应分别注明出口联网、已有账号迁移、手机号登录和导入的实际执行范围。网页入口和出口联网通过不能替代真实 Telegram 验收；已有账号只读资料验证也不等同于新登录或导入通过。

导入提示客户端未能严格断开时，出口占用会保留，防止被其它账号抢用。先重启面板，核对账号是否正式绑定及出口运行状态，再人工恢复；不要删除档案或创建新出口绕过此保护。

运行器最多保留 100 份档案，此保护上限包含取消或失败后保留的注册材料，并非 100 个账号容量承诺。达到上限时拒绝新增注册，仍可管理已有出口；不会自动删除材料释放名额。不再需要的档案应先核对引用并按留存规则备份，再使用删除入口清理，不要反复新建绕过限制。

成功判据是：创建完成后显示本地监听，执行“检测”得到 WARP 成功和出口 IP；绑定后显示显式绑定数和全局使用数符合操作结果。共享验收需检查多个账号实际路由，全局验收需检查继承账号；再确认自动空闲池排除占用项、使用中停止和删除被拒绝。删除验收使用专门的无引用出口，核对进程、代理和档案均移除，并验证批量失败项保留。失败时先检查镜像版本、/data/wgcf-warp 可写性和网络，再使用“恢复”，不要删除持久卷重试注册。

回退至 v1.31.82 或更早版本前，必须先将受管共享或全局路由迁回旧版支持的路由，否则旧版会拒绝连接，不会自动直连。保留数据库、配置和 /data/wgcf-warp 备份，不要恢复指向已删除旧容器的迁移前数据库。回滚镜像不会复原已删除档案或远端注册，恢复本地材料需使用独立备份并重新检查路由及运行状态。

升级前迁移旧容器账号¶

v1.31.82 不再管理或使用旧 kind=warp 代理。若账号或全局配置仍引用旧记录，连接会明确失败，不会自动直连。请在仍支持旧容器的版本上完成迁移：

备份数据库、Session、appsettings.local.json、wgcf-warp 与旧 WARP 卷，记录每个账号的旧代理/全局继承状态；迁移期间避免并发修改这些账号路由。
在已接受 Cloudflare 条款的前提下，为每个账号创建一份轻量出口，确认监听就绪、WARP 检测成功和出口 IP。独立注册与监听不保证 Cloudflare 分配的公网 IP 永远唯一或不变。
逐账号切换至专属新 ProxyId，严格断开旧客户端后，通过该账号路由读取 Telegram 自身资料并回读绑定。只读验收不包含发送消息、加群或其它业务操作。
某账号失败时暂停该账号迁移并保留旧资源；只有全部受影响账号均通过，且旧代理的直接绑定与全局继承引用均为零后，才关闭旧全局配置、移除旧代理和旧容器。旧卷按备份留存策略处理，不能把删除运行容器等同于已经可以销毁私钥备份。
移除部署命令中的旧 WARP Compose 覆盖、Docker Socket 挂载及 TP_WARP_* 配置，使用主 docker-compose.yml 重建面板并升级。验证版本、健康接口、登录态接口、统一列表、逐账号路由和容器重启后的轻量出口恢复。

升级不会自动删除历史记录或外部 Docker 资源。旧状态/刷新接口已撤除；如果仍有旧调用方，应改用轻量档案接口，而不是重启旧容器重试。列表中看见历史记录也不代表该路由可用。回滚应用时保留新路由和注册材料；确需恢复旧容器的灾难恢复，应单独核对备份、容器和账号映射，不能直接回灌迁移前数据库覆盖已经迁移的账号。

2026-10-11 的升级准备已完成 10 个现有账号逐个迁往独立轻量出口：每个账号都回读确认专属代理绑定、WARP 联网检测成功，并通过 GetSelf 只读资料验证，原启用状态保持。当次检测的 10 个出口 IP 互不相同且不同于原出口；这是当次结果，不是固定 IP 或永久唯一性保证。此验收不包含全新手机号/二维码登录、账号导入或 100 账号容量验证。

已升级后的补迁移（v1.31.85）¶

适用于升级后显示“旧出口待迁移”“请迁移至 WARP 新出口”，且已有代理选项为空的安装。镜像升级不会将旧 Docker WARP 自动转换成轻量出口；旧记录也不会作为可选目标。不必降级才能迁移，按以下顺序操作：

先备份数据卷、Session、配置、旧 WARP 卷及原 Compose 文件，记录当前账号代理与全局引用。不要递归执行 chmod -R 755，这会扩大数据库和私钥等材料的读取权限，不能解决迁移问题。
首次切换轻量运行器需要重建面板容器。确认主 Compose 的数据卷仍指向原有目录，将镜像设置为 ghcr.io/moeacgx/telegram-panel:v1.31.85（例如更新 .env 中的 TP_IMAGE），再执行：

bash docker compose -f docker-compose.yml pull telegram-panel docker compose -f docker-compose.yml up -d --no-deps --force-recreate telegram-panel

不再叠加 docker-compose.warp.yml。先保留旧容器和卷，不执行 down -v 或 --remove-orphans。如主 Compose 本身还含旧 Docker Socket 挂载，需要按当前模板移除，并保留自己的数据卷与网络配置。 3. 刷新页面确认版本为 v1.31.85 或更高，在“代理管理 → 一键创建 WARP”创建新出口。名称可留空，待新行显示就绪、检测成功和出口 IP 后再绑定。若注册失败，使用该行“恢复”，不要重复创建。 4. 在“账号管理”中找到仍引用旧出口的账号，使用“切换代理 → 已有代理”选择新出口并保存。也可从新出口“操作 → 添加绑定账号”选择账号；账号可共享同一个新出口，按需要分配。仅修改全局设置不会覆盖账号已有的显式旧代理绑定。 5. 需要全局代理时，在“账号全局代理设置 → 已有代理”选择已检测通过的新出口。需要继承全局的账号还须明确切换到全局模式；逐账号检查新绑定和出口，再执行只读资料验证。 6. 全部旧账号及全局引用清空并验收后，才清理旧代理记录与对应旧容器。仅关闭全局代理不会清除已保存的 ProxyId；继续使用全局代理时先选择有效的新代理。不再使用时，先保存有效的手动全局配置以清除旧编号，再关闭全局代理。确认已保存的旧引用也已清除或替换后，再删除旧代理记录。当前旧出口行仅提示迁移，不提供自动容器清理；不要把删除数据库代理记录当作已停止旧容器。保留旧卷及备份，按前述回滚约束处理。

v1.31.85 修复普通 HTTP 下 crypto.randomUUID is not a function：此前一键创建以及账号切换代理、登录和导入的 WARP 请求编号生成可能失败。该修复不替代 HTTPS 配置，也不自动迁移账号。升级后仍出现相同报错时，先强制刷新确认前端版本，再检查是否仍运行旧镜像；缺少运行器依赖时应重建容器。

前置条件¶

Linux Docker Compose，amd64 或 arm64，面板已有外部 WireGuard WARP API（v1.31.78 基线）。
工具容器可直连 Cloudflare 注册 HTTPS API、WireGuard UDP 端点和 DNS。
面板与工具加入同一受信任 Docker 网络；工具不发布任何宿主机端口。
运营者自行阅读并接受 Cloudflare 应用条款。工具不会默认接受，以下部署和验证命令均不会自动注册。
若要自动绑定，准备当前面板管理员 Cookie。它只在内存中用于 API 请求，不写入配置档案。

wgcf 为非官方 CLI，注册可因上游协议、限流或地区网络变化失败。工具固定 wgcf 2.3.0 和 wireproxy 1.1.3，构建时按 dependencies.json 的 SHA256 校验官方发布资产。WARP+ 订阅设备上限不能解释为普通 WARP 的注册配额；本工具不绑定 WARP+ license。

部署共享容器¶

在仓库根目录执行。若 Compose 网络名不同，先设置 TP_WGCF_NETWORK。

export TP_WGCF_NETWORK=telegram-panel_default
docker compose -f tools/wgcf-warp/compose.yml build
docker compose -f tools/wgcf-warp/compose.yml up -d
docker compose -f tools/wgcf-warp/compose.yml ps

容器名和网络别名均为 tg-wgcf-warp。镜像以 UID/GID 10001 运行，删除全部 capability、启用只读根文件系统；不挂载 Docker Socket、TUN，不授予 NET_ADMIN，不改宿主路由。持久卷只保存本工具档案，默认共享上限 512 MiB 内存、1 CPU、256 PIDs，可按实测调整 Compose。100 份配置是防误操作的硬上限，不是支持容量；一个进程仍消耗 CPU、内存和 UDP 状态。

注册、生成、启停¶

配置名按账号数据库 ID命名，例如账号 ID 123 对应 account-123，不是显示序号。运营者接受条款后自行输入带 --accept-tos 的注册命令；不接受就不执行此步骤。

# 仅在运营者已阅读并接受条款后执行；每次只注册一个独立账号。
docker compose -f tools/wgcf-warp/compose.yml exec wgcf-warp python /app/warpctl.py register account-123 --accept-tos
docker compose -f tools/wgcf-warp/compose.yml exec wgcf-warp python /app/warpctl.py generate account-123 --port 18081
docker compose -f tools/wgcf-warp/compose.yml exec wgcf-warp python /app/warpctl.py start account-123
docker compose -f tools/wgcf-warp/compose.yml exec wgcf-warp python /app/warpctl.py status account-123

每份配置必须使用不同端口。start / stop 保存期望状态，由运行器异步执行；status 的 runtime=listening 仅表示本地进程和 TCP 监听，不代表 Cloudflare/WARP 已连通。 egressVerified 固定为 false，真实出口必须通过下面的面板检测。容器重启后恢复已启动档案。配置生成会拒绝钩子、外部配置和按域名直连选项，所有目的流量均交由 WireGuard。已启动过的档案需要先 stop，等待运行器确认本次请求并显示 stopped 才能重新生成；快速连续执行 stop/generate/start 时，未确认的生成操作会被拒绝。

面板检测并逐账号绑定¶

在仓库外保存 JSON，例如 /srv/tg-wgcf/panel-auth.json：

{"panelUrl":"https://panel.example.com","cookie":"TelegramPanel.Auth=替换为当前管理员Cookie"}

文件的 panelUrl 必须与命令完全一致。设置该文件属主为 UID 10001、权限 0400，父目录避免公开读取。不要在命令参数、Git、工单或日志中粘贴 Cookie。叠加只读凭据挂载：

export TP_WGCF_PANEL_CREDENTIALS=/srv/tg-wgcf/panel-auth.json
docker compose -f tools/wgcf-warp/compose.yml -f tools/wgcf-warp/compose.panel.yml up -d
docker compose -f tools/wgcf-warp/compose.yml -f tools/wgcf-warp/compose.panel.yml exec wgcf-warp \
  python /app/warpctl.py bind --accounts 123 --panel-url https://panel.example.com \
  --credentials /run/secrets/panel-auth.json --proxy-host tg-wgcf-warp

如果只在可信 Docker 网络使用 http://telegram-panel:5000 等地址，必须显式加 --allow-http，且凭据文件也填写该地址；Cookie 会以明文经过该网络。端口以实际面板容器配置为准。工具拒绝 HTTP 重定向，不读取系统代理环境变量，不把 Cookie 转发到其它来源。

--accounts 123,124 按顺序处理，单次最多 10 个；对应档案必须预先注册、生成和启动。每项成功输出账号 ID 和代理 ID。后续项失败时非零退出，之前成功项保留，可原参数重试。工具先读取账号真实 ID 和旧路由，创建外部 SOCKS5 代理，再调用面板出口检测；只有 testStatus=ok、有效出口 IP 和启用状态才通过绑定 API 提交，并回读确认。原代理编号作为 expectedProxyId 传入，发现人工换绑后拒绝覆盖。

旧显式代理为受管 kind=warp 时工具拒绝自动迁移；请在升级前单独安排旧容器账号的迁移、备份和只读 Telegram 验收。普通旧代理及本工具档案不会自动删除，失败也不会改成直连。面板仍允许管理员手动把同一代理分给多个账号，工具无法在 API 之外禁止这种操作；绑定前会拒绝发现已共享或已用作全局代理的新出口。

成功判据与未验证范围¶

首次只验收 1～3 个档案：分别确认注册身份不同、面板出口检测 WARP 开启、账号代理 ID 与档案一致、Telegram 实际操作成功；再验证容器重启恢复、停止单档案时请求失败且不转直连，记录宿主配置、内存、CPU、带宽和错误率后逐步增加。独立注册不保证不同公网 IP。

仓库自动测试使用 fake wgcf/wireproxy 和本地 HTTP 模拟服务器；镜像测试只校验真实 wireproxy 配置解析、不建隧道。真实注册、上游限流、外部 WARP Trace 和 Telegram 业务验证需运营者接受条款后另行完成。只有这些通过后才能判定相应环境可用。

故障排查与回滚¶

注册失败但材料完整：原命令重试会复用材料，再执行 generate，不会再次注册。
注册超时/失败且材料不完整：工具标记结果不明确并拒绝重复注册；保留整个档案，人工核对上游设备。不要靠删文件无限重试，工具不声称能撤销上游注册。
generate 失败：档案标记未生成，不允许启动；检查固定版本程序、网络和配置字段。
runtime=unknown：检查共享容器；backoff 表示子进程退出，30 秒后重试。 failed 表示该档案元数据无效或子进程无法创建，其它档案继续运行。 listening 但面板检测失败时检查 UDP、DNS、Docker 网络和上游可用性。
API 401/403：更换有效 Cookie；敏感原始响应和上游日志有意不输出。
代理创建响应丢失：原参数重试按持久化的唯一名称恢复已有记录；仍找不到时停止并人工核对，不自动重复创建。账号绑定响应丢失则回读当前绑定后恢复。
工具回滚前先核对 meta.json 中 previousProxyId 对应代理或原全局模式仍然有效，并且不是已退役的 kind=warp 路由；确认后在面板切换账号，再执行下列停止命令。不能恢复已删除容器的路由，也不要在账号仍绑定时删除持久卷。

docker compose -f tools/wgcf-warp/compose.yml exec wgcf-warp python /app/warpctl.py stop account-123
docker compose -f tools/wgcf-warp/compose.yml exec wgcf-warp python /app/warpctl.py status account-123
# 整体停用时保留持久卷和账户材料。
docker compose -f tools/wgcf-warp/compose.yml down

停止不会自动解除面板绑定。面板会继续指向停止的代理并报错，不回退直连。v1.31.83 的工具增加本地 delete 命令，要求停止回执已确认；独立调用前仍需自行核对并解除面板引用，工具不会代替面板迁移路由。内置出口优先使用面板删除入口完成引用检查。本地删除不保证注销远端 WARP 设备，退出使用后仍需按自己的留存和远端注销规则处理。