Go 服务端部署指南

适用版本：v1.3.4+

Go 主控是 v1.3.4 新增的轻量主控形态，跨 Windows / Linux / macOS 单二进制运行，聚焦”远程桌面 + 远程终端 + 多用户分级”。与 MFC 主控（YAMA.exe）共享同一套客户端，可混搭部署。

何时选择 Go 主控

选 Go 主控	选 MFC 主控（`YAMA.exe`）
想跑在 Linux 服务器 / Mac mini / ARM 机器上	已经在用 Windows VPS
只需要远程桌面 + 终端 + 多用户	需要文件管理、媒体采集、注册表、品牌定制
给团队多个 viewer 颁号、按设备组授权	单人 / 一人多机日常运维
想做多节点 / 跨实例的授权拓扑实验	自用

Go 主控故意保持轻量——文件管理 / 媒体采集 / 注册表 / 服务管理 / 摄像头 / 录音等功能不在它的范围内，请走 MFC 主控。

1. 获取二进制

git clone https://git.simpleremoter.com/yuanyuanxiang/SimpleRemoter.git
cd SimpleRemoter/server/go

# 当前平台
make build

# 交叉编译
make windows         # Windows amd64
make linux           # Linux amd64

输出位于 server/go/bin/。

2. 最小启动

# Linux / macOS
export YAMA_PWDHASH="61f04dd637a74ee34493fc1025de2c131022536da751c29e3ff4e9024d8eec43"
export YAMA_PWD="your_super_password"
export YAMA_WEB_ADMIN_PASS="your_admin_web_password"
./simpleremoter-server

# Windows
$env:YAMA_PWDHASH = "61f04dd637a74ee34493fc1025de2c131022536da751c29e3ff4e9024d8eec43"
$env:YAMA_PWD     = "your_super_password"
$env:YAMA_WEB_ADMIN_PASS = "your_admin_web_password"
.simpleremoter-server.exe

启动后默认监听：

TCP 6543 — 被控客户端连接端口
HTTP 8080 — 浏览器 Web UI（admin / 上面那个 YAMA_WEB_ADMIN_PASS 登录）

打开 http://localhost:8080，用 admin + YAMA_WEB_ADMIN_PASS 登录，即可看到设备列表。

命令行参数

参数	默认	说明
`-port` / `-p`	`6543`	TCP 端口，分号分隔可多端口（`6543;6544`）
`-http-port`	`8080`	Web UI 端口，传 `0` 禁用
`-no-console`	`false`	关闭控制台输出（守护进程模式）

3. 核心环境变量

主控授权（必需）

变量	说明
`YAMA_PWDHASH`	主控密码 SHA256（64 位十六进制），与客户端授权一致
`YAMA_PWD`	超级密码明文，用于 HMAC 签名验证
`YAMA_WEB_ADMIN_PASS`	Web UI 的 admin 密码；优先于 `YAMA_PWD`。两者都未设 → Web 登录禁用

务必让 YAMA_WEB_ADMIN_PASS 与 YAMA_PWD 不同——Web 是公网暴露面，不应共用主授权密码。

Web 安全

变量	说明
`YAMA_WEB_ALLOWED_ORIGINS`	WebSocket Origin 白名单（逗号分隔）。空 → 仅同源。挂多域名 PWA 时填上
`YAMA_WEB_TRUST_PROXY`	反代场景设 `1`：用 `X-Forwarded-For` 末位作为客户端 IP，让按 IP 限流看到真实 IP。直接暴露公网时严禁开启

多用户配置

变量	说明
`YAMA_USERS_FILE`	非 admin web 用户的持久化 JSON 路径，默认工作目录下的 `users.json`

users.json 在 admin 通过 Web UI 增删用户时自动维护，含 allowed_groups（按设备分组授权）、PBKDF2 密码哈希、salt。

4. 多用户与设备分组

登录后访问 用户管理：

admin 创建 viewer 账号，设置初始密码
给每个 viewer 配置 allowed_groups（设备分组列表）
viewer 登录后只能看到 / 操控分配组内的设备

客户端的”分组”在 BuildDlg 生成阶段写入，随 LOGIN_INFOR 上报到 Go 主控；Go 主控基于此做权限过滤。

5. 生产部署（Nginx + Let’s Encrypt）

Go 主控只跑 plain HTTP，前面挂 Nginx/Caddy 加 TLS。

systemd 单元

/etc/systemd/system/simpleremoter-go.service：

[Unit]
Description=SimpleRemoter Go Master
After=network-online.target

[Service]
Type=simple
User=simpleremoter
WorkingDirectory=/opt/simpleremoter
ExecStart=/opt/simpleremoter/simpleremoter-server -no-console
EnvironmentFile=/etc/simpleremoter/env
Restart=on-failure
RestartSec=5s
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

/etc/simpleremoter/env（权限 chmod 600）：

YAMA_PWDHASH=61f04dd637a74ee34493fc1025de2c131022536da751c29e3ff4e9024d8eec43
YAMA_PWD=your_super_password
YAMA_WEB_ADMIN_PASS=your_admin_web_password
YAMA_WEB_TRUST_PROXY=1
YAMA_WEB_ALLOWED_ORIGINS=https://yama.example.com

启用：

systemctl daemon-reload
systemctl enable --now simpleremoter-go
journalctl -u simpleremoter-go -f

Nginx 反代

/etc/nginx/sites-available/yama.example.com：

upstream yama_go {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name yama.example.com;

    ssl_certificate     /etc/letsencrypt/live/yama.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yama.example.com/privkey.pem;

    # WebSocket 升级（远程桌面流 / 终端 / 设备列表全走 /ws）
    location /ws {
        proxy_pass http://yama_go;
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host       $host;
        proxy_set_header X-Real-IP  $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout  3600s;
        proxy_send_timeout  3600s;
    }

    location / {
        proxy_pass http://yama_go;
        proxy_set_header Host       $host;
        proxy_set_header X-Real-IP  $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

server {
    listen 80;
    server_name yama.example.com;
    return 301 https://$host$request_uri;
}

反代生效后，记得把 YAMA_WEB_TRUST_PROXY=1 一起设上，否则按 IP 限流会全部计在 127.0.0.1 上、整个集群被一锅端封禁。

签证书：

certbot --nginx -d yama.example.com

6. 签名模式（CMD_MASTERSETTING signer）

Go 主控按启动时环境变量自动选择三种签名模式。把签发逻辑从主 HMAC 密钥解耦后，主 HMAC 密钥永远不会出现在下游节点上——这是把 Go 主控部署到自己不完全信任的节点上（家庭实验 / 多组织拓扑 / 公开 demo 实例）的核心安全前提。

模式	触发条件	用途
LocalSigner	`YAMA_SIGN_PASSWORD` 已设	根节点部署。HMAC 直连签名，微秒级延迟
RemoteSigner	`YAMA_LICENSE_SERVER` + `YAMA_LICENSE_TOKEN` 已设	下游节点部署。每次新设备登录 HTTPS POST 到根节点的 License Server 拿签名；同 (clientID, startTime) 缓存 24h（`YAMA_LICENSE_OFFLINE_HRS` 可调）
NoOpSigner	上述都没设	默认 / 公开 demo。返回空签名 → 客户端私有库拒绝启动 screen/file 功能，仅设备列表可用

根节点：作为 License Server

LocalSigner 模式下，再设以下变量即可对外提供 License Server HTTP：

YAMA_SIGN_PASSWORD=<master-hmac-key>
YAMA_LICENSE_PUBLIC_KEY=/etc/simpleremoter/license_pub.pem
YAMA_LICENSE_HTTP_ADDR=:8443

提供两个端点（建议挂 Nginx + TLS 后对外）：

POST /license/sign — body {"client_id":"...","start_time":"..."}，Bearer <下游节点-JWT>，回 {"signature":"<64-hex>"}
POST /license/heartbeat — body {"active_device_count":N,"active_device_ids":[...]}，回 {"server_view_count":M,"drift":N-M}，drift 大于阈值记日志供巡检审核

JWT 校验 alg 锁死 RS256，杜绝 alg:none 攻击。

下游节点：调用根节点的 License Server

YAMA_LICENSE_SERVER=https://license.root.example.com
YAMA_LICENSE_TOKEN=eyJhbGciOiJSUzI1NiI...    # 根节点颁发的 JWT
YAMA_LICENSE_OFFLINE_HRS=24

颁发下游节点 JWT

# 一次性生成 RSA 密钥对（私钥由根节点保管，公钥配给 License Server）
openssl genrsa -out license_priv.pem 2048
openssl rsa -in license_priv.pem -pubout -out license_pub.pem

底层 API 是 licensing.Issue(privKey, sub, tier, maxDevices, ttl)。CLI 包装在独立仓库 yama-issue-token：

yama-issue-token -priv license_priv.pem -sub home-lab -tier trial -max 100 -days 365

Tier	max_devices 默认	备注
`trial`	20	移植 C++ 反代理 RTT 逻辑
`paid`	JWT 必须显式指定	代码层 tier 名沿用上游 Go 代码；本项目无销售计划，所有节点皆按个人 / 研究用途部署

7. 与 MFC 主控并存

两种主控共用同一套客户端。生成客户端时填入哪个主控的 IP/端口，客户端就连哪个；可以同时给一台 Windows MFC 主控 + 一台 Linux Go 主控，覆盖同一批设备群，例如：

Windows MFC 主控负责文件管理 / 取证 / 媒体采集
Linux Go 主控让团队多个 viewer 通过浏览器并行做远程桌面 / 排障

客户端的协议头加密 / XOR / ZSTD / 子连接 auth 完全对齐，无需任何特殊配置。

8. 故障排查

现象	排查
Web 登录提示”密码错误”但密码正确	检查环境变量是否真的注入到了进程（systemd `EnvironmentFile` 路径权限、`systemctl show -p Environment simpleremoter-go`）
客户端连上但 Web 看不到	检查 admin 账号的 `allowed_groups`（admin 默认看所有组；自创建的 viewer 需要显式分配）
远程桌面打开后黑屏	浏览器需支持 WebCodecs（Chrome 94+ / Edge 94+）；Safari 需 iOS 17.4+
反代后限流误封	确认 `YAMA_WEB_TRUST_PROXY=1` 已设且 Nginx 透传 `X-Forwarded-For`
下游节点签名失败	查 `journalctl` 看是否根节点 License Server 不可达；缓存过期后即拒绝签名