部署與升級

首次本地使用先按第一次使用操作。這篇供選擇部署方式、設定遠端存取或升級時查閱。

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。

升級

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 文件。開發依賴、測試和建置命令見本地開發。