二进制部署

不想跑 Docker？下载预编译包，一个二进制加前端静态文件即可运行。当前提供 linux-amd64 包；有 Go 环境的设备也可从源码自行编译（见文末）。

方式一：下载预编译包（推荐）

到 GitHub Releases 下载对应版本的 tunnel-manager_<版本>_linux_amd64.tar.gz（每个打了 v* 标签的版本都会自动构建并附加）。解包：

tar xzf tunnel-manager_v2.4.0_linux_amd64.tar.gz
cd tunnel-manager_v2.4.0_linux_amd64

目录内容：

├── tunnel-manager       # 后端单二进制（静态编译，无依赖）
└── frontend/dist/       # 前端静态文件

运行方式

二进制直接读取环境变量与工作目录下的数据：

# 目录布局（示例）
# /opt/tunnel-manager/
# ├── tunnel-manager
# ├── frontend/dist/
# └── data/                # 首次运行自动生成

export STATIC_DIR=frontend/dist
export STORE_PATH=data/tunnel-manager.db
export PORT=8080
export APP_ENCRYPTION_KEY=<Base64 的 32 字节密钥>
# Cloudflare 凭据二选一：OAuth 三件套 或 CF_API_TOKEN + CF_ACCOUNT_ID
./tunnel-manager

APP_ENCRYPTION_KEY 生成方式：

openssl rand -base64 32

首次打开面板会进入安装引导：面板没有任何账户时只提供安装页面，先选数据库（SQLite 或 PostgreSQL）并测试连接，再填写管理员用户名与密码。密码由你设置，不会打印到日志。

想跳过选择，可以不设置 STORE_PATH 与 DATABASE_URL——引导会把结果写进 data/setup.json，之后的启动照常使用它。

选用 PostgreSQL

默认存储是 SQLite 单文件，个人使用足够；需要多实例、外部备份或已经有 PostgreSQL 时，把存储换成数据库服务即可：

export DATABASE_URL="postgres://tunnel:tunnel@127.0.0.1:5432/tunnel_manager?sslmode=disable"
export DATA_DIR=data

• DATABASE_URL 支持 postgres:// 与 postgresql:// 两种写法，其余连接参数（sslmode、connect_timeout、多主机等）透传给驱动
• 目标库需要预先建好，表结构与迁移由程序在启动时自动创建，无需手工执行 SQL
• DATA_DIR 指定上传文件与心跳日志的存放目录；数据库在远端时默认值是工作目录下的 data/，可用它接已有目录
• 设置 DATABASE_URL 后 STORE_PATH 不再生效；两者都为空时仍是 data/tunnel-manager.db
• 现有 SQLite 数据不会自动搬迁：换库等于全新实例，首次启动会重新走安装引导创建管理员账户，需要按升级、备份与恢复自行导出旧数据

TIP

STATIC_DIR 指向的前端文件与二进制应来自同一个发布包，前后端版本混搭可能出现接口不匹配。

建议配合 systemd 常驻

# /etc/systemd/system/tunnel-manager.service
[Unit]
After=network-online.target
Wants=network-online.target

[Service]
WorkingDirectory=/opt/tunnel-manager
EnvironmentFile=/opt/tunnel-manager/.env
ExecStart=/opt/tunnel-manager/tunnel-manager
Restart=unless-stopped

[Install]
WantedBy=multi-user.target

systemctl daemon-reload && systemctl enable --now tunnel-manager

注意 .env 权限建议 600，里面有加密密钥与 Cloudflare 凭据。

升级

下载新版本包替换二进制与 frontend/dist 并重启服务即可；数据仍在 STORE_PATH 指向的 SQLite 文件（或 DATABASE_URL 指向的数据库）中，备份恢复流程与 Docker 部署通用，详见升级、备份与恢复。

方式二：从源码自行编译（可选）

需要改动代码、或在不提供预编译包的平台（如树莓派等 ARM 设备）上运行时，可在装有 Node.js 与 Go 的机器上自行构建：

# 1. 构建前端静态文件
cd frontend
npm install
npm run build          # 产物在 frontend/dist

# 2. 编译后端单二进制（交叉编译时追加 GOOS / GOARCH）
cd ../backend
CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o tunnel-manager .

得到 tunnel-manager 可执行文件后，按上文相同的目录布局与环境变量运行即可。