部署与升级 | SubLane

使用 Docker 或独立二进制部署 SubLane，配置持久化、HTTPS 和版本升级。

SubLane 以单个进程运行，内嵌管理界面并使用 SQLite。每个数据目录只能由一个运行中的实例使用。生产运行不依赖 Node.js、Redis 或外部数据库。

Docker 镜像

发布镜像为 ghcr.io/murongg/sublane，支持 linux/amd64 和 linux/arm64。Docker 自动选择宿主机架构，公开镜像无需登录 GHCR 即可拉取。

使用固定版本或镜像摘要能让部署可复现。以下手动示例使用已发布的预发布版本 0.1.0-rc.1。latest 仅在正式版发布时更新；不要假定预发布阶段存在 latest。镜像仓库有新版本不会自动更新已运行的容器。

安装脚本

准备 Docker、Compose、Bash、curl 和 jq：

自动选择发布版本

curl -fsSL https://raw.githubusercontent.com/murongg/SubLane/main/scripts/install.sh | bash

脚本优先选择最新正式版，仅在没有正式版时选择最新预发布版，不选择草稿版本。GitHub API 错误会中止安装，不会静默切换发布通道。

安装会创建 ./sublane，校验发布的 Compose 文件、拉取镜像并等待健康检查。镜像版本、宿主机端口和唯一 Compose 项目名写入 .env。脚本不会覆盖已有目录或符号链接；启动失败时会保留配置与已有容器数据。

可以指定版本、新目录与端口：

指定安装参数

curl -fsSL https://raw.githubusercontent.com/murongg/SubLane/main/scripts/install.sh | bash -s -- \
  --version 0.1.0-rc.1 --dir ./team-gateway --port 8088

自动选版需要 jq；文件校验需要 sha256sum 或 shasum。脚本不安装 Docker，也不在本地构建镜像。可先下载脚本源码，检查后执行 bash install.sh --help。

手动 Compose 部署

下载选定发布版本的 Compose 文件：

准备部署目录

mkdir sublane && cd sublane
curl -fsSL https://github.com/murongg/SubLane/releases/download/v0.1.0-rc.1/docker.compose.yaml -o docker.compose.yaml

在同一目录创建 .env：

Compose 环境配置

SUBLANE_IMAGE=ghcr.io/murongg/sublane:0.1.0-rc.1
SUBLANE_BIND_ADDRESS=127.0.0.1
SUBLANE_PORT=8080
SUBLANE_LOG_LEVEL=info
# 配置 HTTPS 反向代理时填写：
# SUBLANE_PUBLIC_URL=https://sublane.example.com

启动并检查服务：

启动与检查

docker compose -f docker.compose.yaml pull
docker compose -f docker.compose.yaml up -d
docker compose -f docker.compose.yaml ps
docker compose -f docker.compose.yaml logs --tail=100 sublane

打开 http://127.0.0.1:8080，先完成管理员初始化，再向团队开放。远程服务器可通过 SSH 隧道访问初始页面。默认端口仅绑定回环地址；向所有网络接口公开需要管理员明确配置。

镜像以非 root 账号运行。Compose 使用只读根文件系统、可写的 /tmp、受限日志和 30 秒停止宽限期，健康检查访问 /readyz。修改内部监听端口时，必须同时修改健康检查和端口映射。

持久化数据

命名卷 sublane-data 保存 /data/sublane.db、相关 WAL 文件和 /data/credentials.key。数据库与加密密钥必须一起保留。

保持 .env、Compose 项目名和目录一致。改变项目名可能创建另一个命名卷，让已有实例看起来像未初始化。升级和恢复时不要执行带 -v 的 docker compose down，它会删除数据卷。

使用宿主机目录挂载时，确保容器内非 root 用户拥有写权限。没有特定路径管理需求时优先使用默认命名卷。

独立 Linux 二进制

从同一个 Release 下载适合架构的压缩包与 SHA256SUMS。linux_amd64 对应 x86-64，linux_arm64 对应 AArch64。校验并解压到新的版本目录后运行：

启动独立二进制

sha256sum --check --ignore-missing SHA256SUMS
./sublane --version
SUBLANE_ADDR=127.0.0.1:8080 SUBLANE_DATA_DIR=/srv/sublane/data ./sublane

数据目录应放在版本化的程序目录之外，由专用服务用户持有并可写。使用进程管理器保持运行，不要以 root 运行网关。

运行配置

变量	默认值	用途
`SUBLANE_ADDR`	`127.0.0.1:8080`	HTTP 监听地址
`SUBLANE_DATA_DIR`	`./data`	SQLite 与加密密钥目录
`SUBLANE_LOG_LEVEL`	`info`	`debug`、`info`、`warn` 或 `error`
`SUBLANE_PUBLIC_URL`	未设置	外部访问的精确来源地址

独立程序读取进程环境变量，不会自动加载 .env。Compose 会读取 .env，完成插值后把相应变量传给容器。

HTTPS 反向代理

团队通过网络访问时使用 HTTPS，并设置外部地址，例如 https://sublane.example.com。只能包含协议、主机和可选端口，不能带路径、查询、片段或用户凭据。

Caddy 示例：

Caddyfile

sublane.example.com {
    reverse_proxy 127.0.0.1:8080
}

Caddy 自动处理 TLS 与 WebSocket 升级。保留默认刷新行为，避免使用负数 flush_interval 改变客户端断开后的取消行为。若代理运行在另一个容器中，应使用同一容器网络内的 sublane:8080，而不是代理容器自己的回环地址。

其他代理也要支持 SSE 与 WebSocket，允许相应的长连接和上传体积。设置 HTTPS 外部地址会启用 Secure 会话 Cookie。网关不会默认信任转发的主机、协议或来源头。

升级

先导出并验证备份，保存数据库与密钥的一致快照。
阅读目标版本发布说明，修改 .env 中的 SUBLANE_IMAGE 为目标固定版本。
拉取、启动并检查：

升级固定版本

docker compose -f docker.compose.yaml pull
docker compose -f docker.compose.yaml up -d
docker compose -f docker.compose.yaml ps
docker compose -f docker.compose.yaml logs --tail=100 sublane

保留同一项目名和数据卷。程序启动时执行数据库迁移。旧程序不一定能够读取新结构，降级应同时恢复升级前的匹配备份，不能只切换旧镜像。

如果实例已经使用恢复目录，后续命令继续包含恢复用的 Compose override，详见备份与恢复。

从源码构建

源码部署

git clone https://github.com/murongg/SubLane.git
cd SubLane
docker compose -f docker.compose.yaml -f docker.compose.build.yaml up --build -d

后续管理命令也使用这两个 Compose 文件。开发依赖、测试和构建命令见本地开发。