部署

本指南涵盖使用 Docker Compose、反向代理及生产级配置进行 PicFast 的生产部署。

Docker Compose（推荐）

使用单一 compose 文件部署完整生产栈（PostgreSQL + PicFast + Traefik 反向代理）：

cd docker
cp .env.traefik.example .env
# 编辑 .env，填入你的域名、密钥和凭据
docker compose -f docker-compose.traefik.yml up -d

首次启动时，会在浏览器中显示初始化向导来创建管理员账号。设置 PICFAST_APP_ADMIN_EMAIL 和 PICFAST_APP_ADMIN_PASSWORD 可在无头部署时自动创建管理员并跳过向导。

Traefik compose 文件包含：

带持久化卷的 PostgreSQL 16
PicFast 应用，通过 Traefik 自动获取 Let's Encrypt SSL 证书
Traefik 反向代理，证书自动续期

Docker Hub 镜像

预构建镜像发布在 Docker Hub：xbeta/picfast。这是推荐的部署方式——无需克隆、无需编译。

用 docker run 快速体验

docker network create picfast-net

docker run -d --name picfast-db --network picfast-net \
  -e POSTGRES_PASSWORD=devonly \
  -v picfast-pgdata:/var/lib/postgresql/data \
  postgres:16-alpine

docker run -d --name picfast --network picfast-net -p 18080:8080 \
  -e PICFAST_DATABASE_URL='postgres://postgres:devonly@picfast-db:5432/postgres?sslmode=disable' \
  -e PICFAST_JWT_SECRET='change-me-in-production' \
  -e PICFAST_SERVER_BASE_URL='http://localhost:18080' \
  -v picfast-uploads:/app/data/uploads \
  -v picfast-thumbnails:/app/data/thumbnails \
  xbeta/picfast:latest

可用标签：

latest — main 分支最新稳定构建
vX.Y.Z — 特定发布版本
sha-<commit> — 按提交追踪的构建标签

上线前检查清单

部署至生产环境前，请确认以下配置：

PICFAST_JWT_SECRET — 使用强随机值（openssl rand -hex 32）
PICFAST_SERVER_BASE_URL — 设置为实际 HTTPS 域名
PICFAST_APP_ADMIN_EMAIL / PICFAST_APP_ADMIN_PASSWORD — 无头部署时设置
POSTGRES_PASSWORD — 勿使用示例密码
反向代理正确透传 Host 与 X-Forwarded-Proto 请求头
反向代理的上传体积限制与实际需求匹配

环境变量

所有配置项均可通过 PICFAST_ 前缀的环境变量进行设置，环境变量优先级高于 config.yaml。完整参考：配置参考。

PICFAST_SERVER_PORT=8080
PICFAST_SERVER_BASE_URL=https://pics.example.com
PICFAST_JWT_SECRET=your-strong-secret
PICFAST_DATABASE_URL=postgres://picfast:picfast@localhost:5432/picfast?sslmode=disable
PICFAST_STORAGE_LOCAL_ROOT=./data/uploads
PICFAST_STORAGE_THUMBNAIL_DIR=./data/thumbnails

反向代理

Nginx

server {
    listen 443 ssl;
    server_name pics.example.com;

    ssl_certificate /etc/ssl/certs/pics.crt;
    ssl_certificate_key /etc/ssl/private/pics.key;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:18080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Caddy

pics.example.com {
    reverse_proxy 127.0.0.1:18080
    request_body {
        max_size 100MB
    }
}

Traefik

在 Docker Compose 服务中添加以下标签：

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.picfast.rule=Host`pics.example.com`"
  - "traefik.http.routers.picfast.tls=true"
  - "traefik.http.services.picfast.loadbalancer.server.port=8080"

数据库备份

docker exec picfast-db pg_dump -U picfast picfast > backup.sql

更新

使用 Docker Hub 镜像时：

docker pull xbeta/picfast:latest
docker stop picfast && docker rm picfast
# 使用相同的卷重新运行 docker run 命令

使用 docker-compose 时：

docker compose pull
docker compose up -d

数据库迁移在启动时自动执行。

家庭网络 & NAS

如需在家庭设备（Synology、QNAP、树莓派等）上部署，并通过隧道（Cloudflare、Tailscale、FRP）将服务开放至公网，请参阅家庭网络 & NAS。

开发环境部署

如需从源码构建（需要 Go 1.26+、Node 20+、pnpm）：

git clone https://github.com/atbeta/picfast.git
cd picfast
make docker-up          # PostgreSQL + Mailpit
cp .env.example .env
go run ./cmd/picfast    # 后端
cd web && pnpm install && pnpm dev  # 前端

更多开发详情请参阅 GitHub README 开发部分。