Docker 自托管部署指南

本文档适用于 个人版 自托管：通过 Docker Compose 一键 启动 网站 + PostgreSQL + MinIO。LifeFrame 镜像从 国内容器仓库 拉取，不从源码构建。

本文档仅适用于个人自托管；项目官方 SaaS 使用 Node 部署，不通过本 Docker Compose。
若在 NAS（群晖、威联通等）上部署，可参见 NAS 快速上手，进阶见 NAS 用户进阶版。

一、概述与前置条件

1.1 自托管的优势

数据主权：照片与元数据存储在你控制的 PostgreSQL 与 MinIO 中
隐私：无需依赖第三方云存储
成本：无按量计费，仅有服务器与带宽成本

1.2 前置条件

项目	说明
Docker	20.10+，并安装 Docker Compose V2（`docker compose`）
域名（可选）	用于 HTTPS 与 `NEXT_PUBLIC_APP_URL`，推荐

PostgreSQL 与 MinIO 已包含在同一 Compose 中，无需自建或使用云数据库 / 云存储。

1.3 资源建议

CPU：2 核及以上
内存：2GB 及以上（推荐 4GB，大量图片时酌情增加）
磁盘：系统与镜像约 2–5GB；照片与 MinIO 数据按实际需求规划

二、架构说明

一键 docker compose up -d 启动三个容器：

┌─────────────────────────────────────────────────────────────────┐
│                        你的服务器 / NAS                          │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────────────┐   │
│  │ PostgreSQL  │   │   MinIO     │   │  LifeFrame (App)    │   │
│  │   :5432     │   │  :9000/9001 │   │  Next.js :3880      │   │
│  └──────┬──────┘   └──────┬──────┘   └──────────┬──────────┘   │
│         │                 │                      │              │
│         └─────────────────┴──────────────────────┘              │
│                 DATABASE_URL / MINIO_* 由 Compose 注入           │
└─────────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │  Nginx (可选)     │  :80 / :443
                    └──────────────────┘

PostgreSQL：存储用户、照片元数据、回忆、标签等；Compose 内建，数据卷 postgres_data。
MinIO：存储图片；Compose 内建，数据卷 minio_data；API :9000，控制台 :9001。
LifeFrame：从国内容器仓库拉取镜像，通过环境变量连接 postgres:5432 与 minio:9000。

三、一键部署

3.1 获取编排文件与 `.env`（可选）

从项目仓库获取 docker-compose.yml。.env 可不创建：镜像地址已写在编排内，NEXT_PUBLIC_APP_URL、POSTGRES_PASSWORD、MINIO_* 等均有默认。部署后按实际访问方式使用即可（内网一般为 **http://服务器或NAS的IP:3880**，有域名则用 https://你的域名）。

若需覆盖，可创建 .env 并填写，例如：POSTGRES_PASSWORD、MINIO_ROOT_USER、MINIO_ROOT_PASSWORD、MINIO_PUBLIC_URL、MINIO_BUCKET；有域名时可将 NEXT_PUBLIC_APP_URL 设为 https://photos.yourdomain.com。镜像地址已写死在 docker-compose.yml，换镜像需直接编辑该文件。

3.2 启动

docker compose up -d

3.3 首次部署：迁移与 MinIO 建桶（已自动完成）

数据库迁移 与 MinIO 建桶 已自动完成，无需手动执行：

迁移：lifeframe 容器启动时会自动执行 prisma migrate deploy。
MinIO 桶：Compose 内 init-minio-bucket 会在 minio 就绪后自动创建与 MINIO_BUCKET（默认 lifeframe）同名的桶。

你只需执行 docker compose up -d，等待 lifeframe 启动完成即可。

初始化套餐（可选）

用于应用内配额与首用户；自托管无需配置付费。仅在需要时，在能访问同一数据库的环境中执行：

pnpm run init:plans

若启用 AI 功能，可再执行：pnpm run init:ai-assistants。

若需手动执行（排查时）

迁移：进入 lifeframe 容器执行 prisma migrate deploy，或使用一次性容器（需 prisma 目录与正确 DATABASE_URL）。
MinIO 桶：打开 http://服务器:9001 用 MINIO_ROOT_USER / MINIO_ROOT_PASSWORD 登录后创建；或使用 mc mb myminio/lifeframe。

3.4 访问

应用：http://主机:3880 或经 Nginx 的地址（端口 3880 以降低与 3000、8080 等的冲突）
MinIO 控制台：http://主机:9001

四、镜像与国内容器仓库

PostgreSQL、MinIO、MinIO 客户端与 LifeFrame 的镜像地址均已写在 docker-compose.yml 中（腾讯云 CCR），国内用户可直接拉取。若需更换镜像或版本，请直接编辑 docker-compose.yml 中对应服务的 image 字段。

五、环境变量参考

变量	必填	说明
`NEXT_PUBLIC_APP_URL`	否	不填则用 `http://localhost:3000`，部署后按实际地址访问（如 `http://主机:3880`）；有域名时建议填
`POSTGRES_PASSWORD`	否	不填则用 `lifeframe_selfhost`；NAS 用户可省略
`MINIO_ROOT_USER`	否	MinIO 控制台账号，默认 `minioadmin`
`MINIO_ROOT_PASSWORD`	否	MinIO 控制台密码，默认 `minioadmin`
`MINIO_PUBLIC_URL`	否	浏览器访问 MinIO 的根地址，默认 `http://localhost:9000`
`MINIO_BUCKET`	否	桶名，默认 `lifeframe`；init 容器会据此自动建桶
`DATABASE_URL`	-	由 Compose 注入，无需在 .env 填写
`SUPER_ADMIN_EMAILS`	否	超管邮箱，逗号分隔
`AI_FEATURES_ENABLED`、`NEXT_PUBLIC_AI_FEATURES_ENABLED`	否	是否启用 AI
`OPENAI_API_KEY`、`ANTHROPIC_API_KEY`、`OPENROUTER_API_KEY`	AI 时	各 AI 服务密钥

六、Nginx 反向代理（可选）

将 80/443 转到 LifeFrame 的 3880 端口：

server {
    listen 80;
    server_name photos.yourdomain.com;
    client_max_body_size 100M;
    location / {
        proxy_pass http://127.0.0.1:3880;
        proxy_http_version 1.1;
        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;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffering off;
    }
}

NEXT_PUBLIC_APP_URL 与 MINIO_PUBLIC_URL 需与最终访问方式一致。HTTPS 可使用 certbot --nginx -d photos.yourdomain.com。

七、备份与恢复

PostgreSQL：docker exec -t <postgres_container> pg_dump -U lifeframe lifeframe | gzip > backup.sql.gz；恢复时 gunzip -c backup.sql.gz | docker exec -i <postgres_container> psql -U lifeframe -d lifeframe。
MinIO：备份 minio_data 卷或使用 mc mirror 同步。
应用与配置：备份 .env、docker-compose.yml 及 Nginx 配置。

八、更新与回滚

更新：

docker compose pull
docker compose up -d

lifeframe 每次启动都会自动执行 prisma migrate deploy，一般无需单独操作。

回滚：将 docker-compose.yml 中 lifeframe 的 image 改为旧版本 tag 后 docker compose pull && docker compose up -d。若存在破坏性迁移，需从备份恢复数据库后再部署旧镜像。

九、常见问题

9.1 启动后 502 / 连接被拒

查看 docker compose logs lifeframe 确认应用已启动；从宿主机访问 http://localhost:3880 测试。
若经 Nginx，检查 proxy_pass 与防火墙。

9.2 登录后跳转错误或循环

将 NEXT_PUBLIC_APP_URL 设为浏览器实际访问的根地址（含协议与域名），并与 Nginx server_name 一致。

9.3 照片上传失败或无法显示

检查 MinIO 桶是否已创建、MINIO_PUBLIC_URL 是否可在浏览器访问；MINIO_ACCESS_KEY / MINIO_SECRET_KEY 与 MINIO_ROOT_USER / MINIO_ROOT_PASSWORD 一致（由 Compose 注入）。

9.4 迁移报错：`relation "xxx" does not exist`

查看 lifeframe 容器启动日志中 prisma migrate deploy 是否有报错；必要时进入容器执行 prisma migrate deploy，或按 3.3「若需手动执行」操作。

9.5 拉取镜像失败

确认 docker-compose.yml 中各 image 地址可访问（当前为腾讯云 CCR）；若镜像尚未推送，需先完成镜像构建与转存后再启动。

9.6 `MINIO_PUBLIC_URL` 怎么填？

MinIO 仅内网、图片经应用或 Nginx 代理时，可填 NEXT_PUBLIC_APP_URL 或实际提供图片的基地址。
MinIO 直接对外（如 http://ip:9000）时，填该地址，并按需配置 Bucket 策略。

十、相关链接

NAS 快速上手 — 群晖、威联通等最简部署
NAS 用户进阶版 — 数据卷、备份、资源限制、常见问题
快速开始
常见问题
项目根目录 README

文档版本：1.0 | 适用 LifeFrame 个人版 Docker 自托管

On this page