Xboard-Node 是 Xboard 的节点后端。上游项目当前 README 说明支持 sing-box / xray-core 双内核,并提供 Docker、Compose 和 systemd 等部署方式。接口、协议和参数会随版本变化,操作前请以上游仓库和对应发布说明为准。

部署前准备

  • 已有可访问的 Xboard 面板,并在面板端创建了对应节点。
  • 准备该节点的面板 API 地址、节点 API 密钥和节点 ID。这里的 apiKey 是面板发给节点后端使用的密钥,不是用户订阅链接或管理员登录密码;nodeID 必须对应面板端创建的那一项。
  • 服务器已安装 Docker,并确认防火墙/云安全组仅开放节点实际需要的端口。--network host 会让容器共享宿主机网络命名空间,不能把它理解为自动安全隔离。

使用 env 文件运行 Docker

先创建仅 root 可读的环境变量文件:

sudo install -m 600 /dev/null /etc/xboard-node.env
sudoedit /etc/xboard-node.env

文件内容:

apiHost=https://panel.example.com
apiKey=替换为面板提供的节点密钥
nodeID=1234

将面板域名、密钥和节点 ID 替换为自己的值。启动容器时优先使用明确版本标签,并在升级前核对发布说明:

docker run -d \
  --name xboard-node \
  --restart unless-stopped \
  --network host \
  --env-file /etc/xboard-node.env \
  ghcr.io/cedar2025/xboard-node:v1.13

示例版本来自本次核对时上游容器发布页显示的标签;部署时请检查最新发布,不要假定文中版本永远最新。env 文件可以避免把密钥直接写进 shell 命令历史,但拥有 Docker 管理权限的用户仍可能读取容器配置;服务器应限制 Docker/socket 管理权限。不要把 env 文件、真实 API 密钥或包含它的截图提交到仓库。

如果使用 Compose 或 systemd,请以上游 README给出的当前模板为准。上游示例配置中对应字段为 panel.url、panel.token、panel.node_id;Docker 环境变量与配置文件的键名格式不同,勿混写。

确认容器是否运行

docker ps --filter name=xboard-node
docker logs --tail 100 xboard-node

持续观察启动日志:

docker logs -f xboard-node

先检查日志中是否有配置解析、面板连接、认证失败、节点 ID 不存在或端口占用等错误。上游版本和日志措辞会变化;报告问题时附版本、系统架构、时间和脱敏错误上下文,不要贴完整密钥。

节点没有上线时

  1. 容器立即退出: 查看 docker ps -a 和 docker logs xboard-node,优先处理启动报错,不要反复重建容器丢掉现场。
  2. 面板无法连接: 在节点服务器检查面板域名解析、HTTPS 连通性、系统时间和证书链;确认 apiHost 带正确协议及面板要求的地址路径。
  3. 认证失败或节点不存在: 对照面板端节点的 nodeID 和对应 API key,确认没有把用户订阅 token 或管理员密码误填进去。密钥泄漏后在面板端轮换并更新容器配置。
  4. 容器在运行但面板离线: 核对服务器出站网络、面板访问策略、面板侧节点配置及双方版本兼容信息;docker ps 显示 Up 只表示进程在运行,不代表面板握手成功。
  5. 端口冲突或协议不能用: 查看容器日志、宿主机监听端口和云防火墙规则,确保面板端节点配置的协议/端口与后端实际配置一致。

更新和回退

先备份部署配置并记录当前镜像标签,再拉取并替换容器。避免长期依赖 latest,这样升级时间和回退版本更可控。若升级后节点离线,保留日志,回到上一个确认可用的镜像标签并对照上游变更记录;不要同时升级面板、节点后端和系统网络设置。

参考资料