部署与升级

首次本地使用先按第一次使用操作。这篇供选择部署方式、配置远程访问或升级时查阅。

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

Docker 镜像

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

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

安装脚本

从终端运行安装脚本，按提示选择 Docker 或 Linux 预编译二进制、普通实例或只读演示，再选择不配置代理、Caddy 或 Nginx：

使用 ↑/↓ 或数字键选中选项，再按 Enter 确认；默认选中第一项。不支持菜单显示的终端会使用数字输入提示。域名仍通过文本输入，部署前会展示生成的配置供确认。通过参数指定的选项会跳过对应选择；加上 --non-interactive 可关闭全部交互提示。

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

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

脚本先对照 SHA256SUMS 校验选中的发布文件，再安装到新的 ./sublane 目录。Docker 模式需要 Docker Compose，会拉取镜像并等待容器健康检查。二进制模式支持 Linux amd64/arm64，需要可用的 systemd 用户管理器；脚本会启用用户服务并等待 /readyz。脚本不会安装 Docker、Caddy 或 Nginx，也不会从源码构建。

没有交互终端时，默认安装普通实例，选择 Docker 且不配置代理。也可以用参数明确指定版本、目录、端口和部署方式：

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 --runtime docker --proxy none

脚本会使用 ss（iproute2 提供）或 lsof，在下载前和创建部署目录前检查 SubLane 的端口。如果该端口已有回环地址或通配地址的监听服务，脚本会停止，并提示用 --port 选择空闲端口，例如 --port 8088；两个检测工具都没有安装时，会提示先安装其中一个。已有代理使用 80、443 端口，不会阻止使用后端端口 8080 的安装。检查不会预留端口，检查后出现的冲突仍由启动健康检查发现。

例如，安装二进制并生成面向公网域名的 Caddyfile：

curl -fsSL https://raw.githubusercontent.com/murongg/SubLane/main/scripts/install.sh | bash -s -- \
  --runtime binary --proxy caddy --domain sublane.example.com

--domain 对 Caddy 和 Nginx 都不是必填项。留空时，生成的代理配置只在 127.0.0.1:80 提供 HTTP，且不设置 SUBLANE_PUBLIC_URL；填写域名时，脚本自动设置 SUBLANE_PUBLIC_URL=https://<域名> 并生成 HTTPS 配置。脚本会先展示配置供检查，不会将配置安装到代理服务，也不会重载代理。Nginx 模板默认使用 /etc/letsencrypt/live/<域名>/ 下的证书，请按实际路径修改。

Docker 模式将镜像版本、宿主机端口和唯一 Compose 项目名写入 .env，应与 docker.compose.yaml 一起保留，以维持同一数据卷。二进制模式生成 sublane.env、start.sh 和 systemd 用户单元，数据保存在私有的 data/ 目录。若希望注销登录后服务继续运行，需检查 loginctl show-user "$USER" -p Linger，并按需启用 lingering。新安装不会覆盖已有目录或符号链接；脚本安装的已有实例可以按下文更新。启动失败时会保留配置和已创建的数据。

自动选版需要 jq；文件校验需要 sha256sum 或 shasum。可先下载脚本源码，检查后执行 bash install.sh --help。

更新脚本安装的实例

先导出并验证数据库备份，阅读目标版本的发布说明。在安装目录的上一级运行脚本；交互终端发现已有目录后会提供 Update existing instance 选项，并在部署前确认。也可以明确指定更新：

curl -fsSL https://raw.githubusercontent.com/murongg/SubLane/main/scripts/install.sh | bash -s -- \
  --update --dir ./sublane

未指定 --version 时沿用安装的选版规则：优先最新正式版，没有正式版时选择最新预发布版。可加上 --version <已发布版本> 固定版本、--wait-timeout 120 调整就绪等待时间，或 --non-interactive 跳过确认。脚本自动识别原有运行方式；更新不能同时传入 --runtime、--port、--proxy、--demo 等安装专用选项。

Docker 更新保留 Compose 文件和项目名，只修改 .env 中的 SUBLANE_IMAGE，拉取目标镜像并等待重新创建的服务健康。二进制更新校验压缩包后替换可执行文件及随包文档和许可文件，重启原 systemd 用户服务并等待 /readyz。已有环境配置、启动脚本、服务单元、代理配置和数据路径均保留。更新时原服务可能正在占用端口，因此不执行新安装的空闲端口检查。

下载、校验、配置检查或拉取镜像失败时，现有部署文件保持不变。替换前，脚本将旧程序或配置保存到安装目录内私有的 .update-backup.* 目录，并显示其路径。这不是数据库备份。 启动失败时会保留恢复文件和当前数据、报告失败，不会自动用旧版本打开可能已迁移的数据库。需要恢复数据时，请按备份与恢复操作。脚本拒绝并发更新；进程被强制终止后，须先确认没有更新仍在运行，再移除遗留的 .update-lock。

此功能用于脚本创建的安装。手动部署或依赖额外 Compose override 文件的实例，请继续使用下文升级步骤，并在后续启动中包含全部 override。

手动 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：

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 中先确认容器实际看到的代理来源地址：
# SUBLANE_TRUSTED_PROXIES=<代理来源 IP>/32

启动并检查服务：

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 运行网关。

交互式安装脚本也可以完成二进制安装，并使用 systemd 用户服务管理进程。

演示模式

安装脚本支持交互选择「普通实例」或「只读演示」，默认仍为普通实例。也可以直接传入 --demo：

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

--demo 同时适用于 --runtime docker 和 --runtime binary；添加 --non-interactive 可让其余选项使用默认值。脚本会将 SUBLANE_DEMO=true 写入 Docker 的 .env 或二进制服务的 sublane.env，安装完成后显示演示账号。外部环境中已有的 SUBLANE_DEMO 不会覆盖安装器的选择。

所选发布版本的已校验配置必须包含 Demo 支持。旧版本会在拉取、启动容器或启用服务前被拒绝；可用 --version 指定已包含该功能的发布版本，不会静默改成普通实例。

使用包含演示功能的构建版本，通过环境变量启动只读演示服务：

SUBLANE_DEMO=true ./sublane

打开服务地址，在登录页点击「进入演示」，或使用用户名 demo、密码 sublane-demo 登录。页面会明确标注示例数据，包含订阅账号、资源组、成员、密钥元数据、请求记录和近 30 天用量。可浏览页面、筛选记录、切换语言和主题，也可以查看表单；修改、凭据复制、OAuth、备份和真实网关调用（包括 WebSocket）均被拦截，登录和退出仍可使用。

每次启动都会创建独立的临时数据库和加密密钥，不打开 SUBLANE_DATA_DIR、价格缓存或真实凭据，不访问真实提供方及版本、价格服务。正常退出会清理临时文件；强制终止进程可能在系统临时目录留下 sublane-demo-* 目录。重启会重新生成日期较新的示例数据。停止演示并取消 SUBLANE_DEMO 后，可恢复正常实例。

本地开发可运行 SUBLANE_DEMO=true make dev。使用本版本的 Compose 文件时，在 .env 中设置 SUBLANE_DEMO=true，再重新创建容器。尚未包含演示功能的旧版本需要先升级或从源码构建。监听地址、外部域名与可信代理的配置方式保持一致。

运行配置

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

SUBLANE_MAX_REQUEST_BODY_MB 同时限制网关 HTTP 请求体、WebSocket 消息和重建后的对话上下文。响应体和流事件仍分别限制为 8 MiB。修改后需重启独立服务或重建容器，并同步调整反向代理的请求体上限。

自定义 SUBLANE_PRICING_URL 时，应同时设置匹配的 SUBLANE_PRICING_HASH_URL 才能继续校验价格文件的 SHA-256。只设置自定义价格 URL 时，文件仍会下载和解析，但不会进行哈希校验。

网关运行参数变更后需重启进程或重建容器。当前 Compose 文件会传入这些变量；脚本升级保留已有 Compose 文件，旧安装应先补充对应的 environment 条目，再使用 .env 覆盖。账号与成员并发设置仍独立持久化。

HTTPS 反向代理

团队通过网络访问时使用 HTTPS，并设置精确的外部地址，例如 SUBLANE_PUBLIC_URL=https://sublane.example.com。反代部署应设置此项；否则来源检查会回退到请求的 Host 头。地址只能包含协议、主机和可选端口，不能带路径、查询、片段或用户凭据。保留原始 Host 头，并支持 SSE 和 WebSocket。

SUBLANE_TRUSTED_PROXIES 应填写直接连接 SubLane 的自有代理的 CIDR，而不是访客地址。独立二进制通过本机 IPv4 回环接入代理时可用 127.0.0.1/32；若代理走 IPv6 回环，再加 ::1/128。Docker 容器看到的宿主机代理地址可能是网桥地址，安装脚本在 Docker 模式下默认留空；先确认容器内实际看到的来源地址，再通过 --trusted-proxies 或 .env 配置。只信任固定代理地址或专用的小范围网段，并限制绕过代理直接访问 SubLane。未配置时，所有经同一代理访问的用户会共用该代理的登录限流额度。

Caddy 示例：

sublane.example.com {
    reverse_proxy 127.0.0.1:8080
}

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

对于已有的 Nginx，把 map 放在 http 配置层级，下面两个 location 放进 HTTPS 的 server 块：

map $http_upgrade $sublane_connection {
    default upgrade;
    ''      close;
}

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $sublane_connection;
    proxy_buffering off;
    proxy_read_timeout 650s;
    proxy_send_timeout 650s;
    client_max_body_size 128m;
}

# 网页备份上传与下载可能更大，最长约 15 分钟。
location /api/settings/backup/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_request_buffering off;
    proxy_buffering off;
    proxy_read_timeout 950s;
    proxy_send_timeout 950s;
    client_max_body_size 256m;
}

在上层 Nginx server 中配置 HTTPS 证书。其他代理也要支持 SSE 与 WebSocket，允许相应的长连接和上传体积。设置 HTTPS 外部地址会启用 Secure 会话 Cookie；未配置可信代理时，网关不会信任 X-Forwarded-For。

网页更新

平台所有者可进入「管理 → 系统设置 → 软件更新」，检查 SubLane 官方正式版。检查结果缓存一小时，手动检查间隔至少一分钟；检查本身不会安装软件。网页安装支持脚本管理的 Linux Docker 和二进制正式版实例；自定义部署、预发布版和开发构建仍使用手动升级。

首次需升级到包含本功能、并在 Release 中提供校验过的 install.sh 与 updater.sh 的版本，同时启用宿主机更新进程。在安装目录的上一级运行：

curl -fsSL https://raw.githubusercontent.com/murongg/SubLane/main/scripts/install.sh | bash -s -- --update --enable-updates --dir ./sublane

新安装可去掉 --update，保留 --enable-updates。两种模式均要求 Linux、jq 和可用的 systemd 用户管理器；请确保退出登录后用户管理器仍在运行，启用用户驻留可能需要管理员配置。已有自定义 Compose override（包括恢复目录配置）的实例须按手动步骤升级。

安装器创建独立的 systemd 用户更新服务及私有 .updater/ 目录。Docker 仅挂载 .updater/mailbox，通过 SUBLANE_UPDATE_DIR=/run/sublane-updates 访问任务；应用不持有 Docker socket。二进制模式在 sublane.env 中保存任务目录的绝对路径。请随部署保留 .updater/。手动管理已启用更新的 Docker 实例时，需包含生成的覆盖文件：

docker compose -f docker.compose.yaml -f .updater/compose.yaml ps

先导出并验证当前备份，再点击「更新至…」并确认已备份。宿主机进程下载并校验文件，保留配置、数据和服务标识，重启后检查就绪状态。页面会重连，只有目标版本已提供服务才显示完成。进行中的请求可能中断；成功后刷新页面加载配套前端。

失败和中断状态会保留。重试前请在宿主机查看 .updater/last.log 以及 updater-sublane-*.service 用户服务，日志不会通过网页返回。更新进程重启后不会重复执行中断的安装。新进程可能已经迁移 SQLite，因此启动失败时不会自动降级；如需恢复旧数据，请使用验证过的备份。停止并禁用更新用户服务后，网页安装关闭，版本检查仍可使用。

升级

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

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

保留同一项目名和数据卷。启动时会初始化新数据库，并为受支持的已有数据库执行缺失的增量迁移；包含 001_settings.sql 的早期不兼容预发布结构会被拒绝，应保留旧目录后另建数据目录。升级前先导出并验证备份；仅切换镜像不能回滚已经迁移的数据。

如果实例已经使用恢复目录，后续命令继续包含恢复用的 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 文件。开发依赖、测试和构建命令见本地开发。

独立凭据密钥与密码加密备份的迁移步骤见备份与恢复。已有部署在配置可选路径前继续使用原密钥位置。