部署

PicFast 提供多种部署方式。对于大多数用户，Docker Compose + 反向代理是兼顾简便与生产就绪的最佳选择。

Docker Compose（推荐）

下载 Compose 文件和环境变量模板，无需克隆仓库：

mkdir picfast && cd picfast
wget https://raw.githubusercontent.com/atbeta/picfast/main/docker/docker-compose.yml
wget https://raw.githubusercontent.com/atbeta/picfast/main/docker/.env.example -O .env

编辑 .env，填入你的域名、密钥和凭据，然后：

docker compose up -d

Compose 文件包含 PostgreSQL 16 和 PicFast。默认 PicFast 绑定到 127.0.0.1:18080 — 前置 Nginx、Caddy 或 NPM 即可提供 HTTPS。如需直接暴露到网络，在 .env 中设置 PICFAST_HTTP_BIND=0.0.0.0。

首次启动后打开站点，跟随引导向导创建管理员。在 .env 中设置 PICFAST_APP_ADMIN_EMAIL 和 PICFAST_APP_ADMIN_PASSWORD 可自动创建管理员并跳过向导。

数据存储在当前目录下：

• Postgres：./data/postgres
• 上传文件：./data/uploads
• 缩略图：./data/thumbnails

Traefik（需已有 Traefik 及证书）

如果已有运行中的 Traefik 实例并配置了 TLS 证书，可使用此方案：

mkdir picfast && cd picfast
wget https://raw.githubusercontent.com/atbeta/picfast/main/docker/docker-compose.traefik.yml
wget https://raw.githubusercontent.com/atbeta/picfast/main/docker/.env.traefik.example -O .env

vim .env  # 设置域名、数据库密码、JWT 密钥
docker compose -f docker-compose.traefik.yml up -d

确保 .env 中 TRAEFIK_DOCKER_NETWORK 与 Traefik 所在网络一致。

Docker Hub 镜像（docker run）

预构建镜像在 Docker Hub，适用于快速测试或自定义部署：

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

可用镜像标签见 Docker Hub。

上线前检查清单

• JWT 密钥：设为高强度随机值（openssl rand -hex 32）
• 站点地址：设置为实际 HTTPS 域名
• 管理员凭据：无头部署时设置，或使用初始化向导
• 数据库密码：生产环境勿使用示例值
• 反向代理正确透传 Host 和 X-Forwarded-Proto 请求头
• 反向代理的上传体积限制与实际需求匹配（默认每文件 50 MB）

环境变量

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

PICFAST_SERVER_PORT=8080
PICFAST_SERVER_BASE_URL=https://picfast.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 picfast.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

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

可观测性（Prometheus）

PicFast 在独立内部端口（:9190）暴露 Prometheus 指标。Docker Compose 不会将此端口发布到宿主机，Prometheus 通过 Docker 网络抓取：

scrape_configs:
  - job_name: picfast
    metrics_path: /metrics
    static_configs:
      - targets: ["app:9190"]

/health 端点在数据库和存储可达时返回 200。指标涵盖 HTTP 请求数、上传吞吐量、数据库连接池状态等。

备份与维护

需要整实例归档（数据库与可选对象）、校验包、恢复预检与一致性巡检时，请使用内置 picfast maintenance 命令行，详见 备份与维护。

若仅需从 Postgres 导出纯 SQL，可直接对数据库容器执行（示例，容器名与库名以实际为准）：

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

更新

docker compose pull
docker compose up -d

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

家庭网络 & NAS

如需在 Synology、QNAP、TrueNAS、Unraid 或树莓派上部署，并通过 Cloudflare/Tailscale/FRP 隧道暴露到公网，见 家庭网络 & NAS。