Ubuntu Node Bridge

一个面向多台 Ubuntu 电脑的轻量、安全通信桥。控制端可以通过经过鉴权的 JSON API 并发查询节点健康状态、系统信息和磁盘使用情况。项目源自真实多机管理模式， 但已删除所有私有节点、凭据、日志和业务逻辑。

A small, secure communication bridge for multiple Ubuntu computers. It provides authenticated health checks and a fixed command registry, with no third-party runtime dependencies and no arbitrary remote shell endpoint.

Features / 功能

• Python 标准库实现，支持 Python 3.10+
• Bearer Token 鉴权，并使用常量时间比较
• 默认监听 127.0.0.1，推荐通过 SSH 隧道连接
• 多节点并发查询，节点配置不保存 Token 明文
• 固定命令：ping、system_info、disk_usage
• systemd 安全加固示例和 MIT 许可证

Architecture / 架构

Controller                 SSH tunnels                 Ubuntu nodes
ubuntu-node  ───────►  127.0.0.1:18765  ───────►  agent:127.0.0.1:8765
             └──────►  127.0.0.1:28765  ───────►  agent:127.0.0.1:8765

HTTP 提供简单、可检查的 JSON 协议；SSH 负责加密、主机身份验证和端口转发。 设计理由见 ADR-001。

Quick Start / 快速开始

1. Install / 安装

git clone https://github.com/Tmigu/ubuntu-node-bridge.git
cd ubuntu-node-bridge
python3 -m venv .venv
. .venv/bin/activate
pip install .

2. Start an agent / 启动节点 Agent

在每台 Ubuntu 节点生成独立 Token：

export NODE_BRIDGE_TOKEN="$(python3 scripts/generate_token.py)"
ubuntu-node-agent

生产节点可使用安装脚本，它会创建受限系统用户、独立虚拟环境、Token 文件和 systemd 服务：

sudo scripts/install_agent.sh
sudo systemctl status ubuntu-node-bridge

3. Create SSH tunnels / 创建 SSH 隧道

在控制端分别建立隧道；把示例主机名替换成你自己的 SSH 配置别名：

ssh -N -L 18765:127.0.0.1:8765 ubuntu-node-01
ssh -N -L 28765:127.0.0.1:8765 ubuntu-node-02

不要使用 StrictHostKeyChecking=no。首次连接时请核对主机指纹。

4. Configure and query / 配置并查询

cp config/nodes.example.json config/nodes.json
export UBUNTU_NODE_01_TOKEN='token-created-on-node-01'
export UBUNTU_NODE_02_TOKEN='token-created-on-node-02'

ubuntu-node --nodes config/nodes.json health
ubuntu-node --nodes config/nodes.json system_info
ubuntu-node --nodes config/nodes.json disk_usage

config/nodes.json 已被 Git 忽略。Token 仅从环境变量读取，不能写进节点 JSON。

API

GET /v1/health

返回节点名称、平台和支持的命令。

POST /v1/commands

{"command":"ping"}

仅接受固定命令名称，不接受命令参数或 Shell 字符串。

Development / 开发

python3 -m unittest discover -s tests -v
python3 -m compileall -q src tests
bash -n scripts/*.sh

Security / 安全

Bearer Token 不会加密 HTTP。保持默认回环监听并使用 SSH 隧道；如果必须直接监听 局域网地址，请使用 TLS 或加密覆盖网络，并限制防火墙来源。完整说明见 SECURITY.md。

License

MIT © 2026 aber