Xboard Node Docker 部署:API 参数、日志与节点离线排查
本文目录
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 不存在或端口占用等错误。上游版本和日志措辞会变化;报告问题时附版本、系统架构、时间和脱敏错误上下文,不要贴完整密钥。
节点没有上线时
- 容器立即退出: 查看
docker ps -a和docker logs xboard-node,优先处理启动报错,不要反复重建容器丢掉现场。 - 面板无法连接: 在节点服务器检查面板域名解析、HTTPS 连通性、系统时间和证书链;确认
apiHost带正确协议及面板要求的地址路径。 - 认证失败或节点不存在: 对照面板端节点的
nodeID和对应 API key,确认没有把用户订阅 token 或管理员密码误填进去。密钥泄漏后在面板端轮换并更新容器配置。 - 容器在运行但面板离线: 核对服务器出站网络、面板访问策略、面板侧节点配置及双方版本兼容信息;
docker ps显示 Up 只表示进程在运行,不代表面板握手成功。 - 端口冲突或协议不能用: 查看容器日志、宿主机监听端口和云防火墙规则,确保面板端节点配置的协议/端口与后端实际配置一致。
更新和回退
先备份部署配置并记录当前镜像标签,再拉取并替换容器。避免长期依赖 latest,这样升级时间和回退版本更可控。若升级后节点离线,保留日志,回到上一个确认可用的镜像标签并对照上游变更记录;不要同时升级面板、节点后端和系统网络设置。
参考资料
Xboard 的其他教程
软件页 →- 文章标题
- Xboard Node Docker 部署:API 参数、日志与节点离线排查
- 本文链接
- https://www.gowall.net/software/xboard/xboard-node-docker/
- 版权说明
- 版权所有,保留所有权利。