自架 ShareX 神器 Zipline

This article is not available in English yet. Showing the original.

Also available in: 繁體中文

什麼是 Zipline？

Zipline 是一套用 TypeScript 開發、被稱為「next-generation ShareX server」的自架檔案上傳與分享服務。它不只是單純的圖床，而是把檔案託管、螢幕截圖上傳、短網址、程式碼分享整合在同一套服務裡：

5 items

可以直接當作 ShareX、Flameshot 等截圖工具的上傳端點，截圖後自動上傳並複製連結，取代 Imgur、file.io 這類雲端服務，資料完全留在自己的主機上。

適合的使用情境

如果你原本習慣用 ShareX 截圖後丟去 Imgur 或雲端硬碟，或是團隊需要一個內部的檔案/連結分享站，Zipline 幾乎是目前自架方案裡功能最完整、上手也最快的選擇——用 Docker 幾分鐘就能部署起來。

最近想架一個私有圖床/檔案分享服務，選了 Zipline。剛好主機上已經有一個共用的 PostgreSQL 容器在跑，所以這篇記錄怎麼讓 Zipline 接到既有的資料庫，而不是額外再開一個 PostgreSQL 容器，最後再用 Caddy 把服務掛到子網域上。

環境說明

本篇的 PostgreSQL 與 Zipline 是同一台主機上的兩個獨立 Docker Compose 專案，PostgreSQL 對外開了 5434 port。因為同機，所以會透過 Docker network 直接互通，而不是打主機 IP。

前置條件

主機上已經有一個獨立跑的 PostgreSQL 容器（本文用 postgres:18.4-bookworm）
該 PostgreSQL 的 compose 檔已建立一個外部可共用的 network，例如 pg-network
已安裝 Docker 與 Docker Compose

既有的 PostgreSQL compose 大致長這樣：

YAML

services:
  postgres:
    image: postgres:18.4-bookworm
    container_name: postgres18
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-admin}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-changeme}
    ports:
      - "5434:5432"
    volumes:
      - /volume1/docker/postgres:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-admin}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - pg-network

networks:
  pg-network:
    name: pg-network

重點是 networks.pg-network 有給 name，這樣其他 compose 專案才能用 external: true 接進來。

建立資料庫帳號

先連進 PostgreSQL，幫 Zipline 建一個專用帳號跟資料庫：

Bash

psql -U admin -p 5434 -h localhost

SQL

CREATE USER zipline WITH PASSWORD 'your_password_here' CREATEDB;
CREATE DATABASE zipline OWNER zipline;

別忘了 CREATEDB

Zipline 第一次啟動時，migration 流程會嘗試自己建立資料庫，如果帳號沒有 CREATEDB 權限，會直接在啟動階段噴錯：permission denied to create database。就算資料庫其實已經手動建好了，這個權限還是建議保留，避免版本升級時的自動遷移流程再次卡住。

Zipline 的 Docker Compose

因為 PostgreSQL 是別的專案管理的，Zipline 這邊的 compose 只需要一個 service，並且加入既有的 pg-network：

YAML

services:
  zipline:
    image: ghcr.io/diced/zipline:latest
    restart: unless-stopped
    ports:
      - '7652:3000'
    env_file:
      - .env
    environment:
      - DATABASE_URL=postgres://${POSTGRESQL_USER:-zipline}:${POSTGRESQL_PASSWORD}@postgres:5432/${POSTGRESQL_DB:-zipline}
    volumes:
      - './uploads:/zipline/uploads'
      - './public:/zipline/public'
      - './themes:/zipline/themes'
    healthcheck:
      test: ['CMD', 'wget', '-q', '--spider', 'http://0.0.0.0:3000/api/healthcheck']
      interval: 15s
      timeout: 2s
      retries: 2
    networks:
      - pg-network

networks:
  pg-network:
    name: pg-network
    external: true

幾個重點：

3 items

同一個 Docker network 內，容器之間可以直接用 service name（這裡是 postgres）互相解析，不需要打 192.168.x.x 或 localhost。這也是為什麼即使兩邊是不同的 compose 專案，只要接進同一個 network 就能直接互通。

第一次 docker compose up 時可能會看到：

Text

WARN a network with name pg-network exists but was not created for project "zipline".
Set `external: true` to use an existing network

只要 compose 裡已經設定 external: true，這條只是提醒訊息，容器仍會正常啟動並加入該 network。

.env 設定

Text

POSTGRESQL_USER=zipline
POSTGRESQL_PASSWORD=your_password_here
POSTGRESQL_DB=zipline

# Zipline 必填，用來簽發 session 等用途
CORE_SECRET=改成一段隨機字串

CORE_SECRET 是 Zipline 啟動時的必填項，缺少的話會在 config 驗證階段直接失敗：

Text

ERROR config.validate CORE_SECRET: Invalid input: expected string, received undefined

可以用以下指令產生一段隨機字串：

Bash

openssl rand -base64 32

啟動

Bash

docker compose up -d
docker compose logs -f

看到類似訊息就代表資料庫連線與 migration 都順利完成：

Text

[INFO   db] connecting to database
[INFO   server] starting zipline mode="production" version="4.6.5"

啟動後可以先用容器內部指令確認健康狀態：

Bash

docker exec zipline-zipline-1 wget -q --spider http://0.0.0.0:3000/api/healthcheck && echo "✓ Zipline 健康狀態正常"

用 Caddy 反向代理到子網域

假設要把服務掛在 demo.sao-x.com，並且對外用 7652 port，Caddyfile 大概長這樣：

Text

demo.sao-x.com {
    reverse_proxy localhost:7652
}

如果 Caddy 跟 Zipline 不是同一台主機，localhost 記得換成 Zipline 所在主機的實際 IP。設定完重新載入 Caddy：

Bash

caddy reload

之後就能透過 https://demo.sao-x.com 存取 Zipline，Caddy 會自動處理 HTTPS 憑證。

完成畫面

部署完成後，登入管理後台，首頁大致會像這樣：

小結

整體流程其實不複雜，卡關的地方主要有兩個：一是資料庫帳號權限不足導致 migration 失敗，二是忘記设定 CORE_SECRET 造成啟動時的 config 驗證失敗。只要把這兩點顧好，加上 Docker network 讓兩個獨立的 compose 專案互通，就能很輕鬆地讓 Zipline 共用既有的 PostgreSQL，不用額外再開一個資料庫容器。

什麼是 Zipline？

01ShareX / Flameshot 原生支援

02檔案託管與整理

03URL 縮網址

04安全與帳號管理

05彈性儲存與整合

前置條件

建立資料庫帳號

Zipline 的 Docker Compose

01DATABASE_URL 裡的 host 要用 service name

02Port 要用容器內部的 5432

03external network 會有一條 WARN，可以忽略

.env 設定

啟動

用 Caddy 反向代理到子網域

完成畫面

小結