自托管部署

最小配置

复制示例环境文件到 backend 目录并修改（compose 的 env_file 读的是 ./backend/.env；根目录 .env 只用于 compose 变量替换，如 MINIO_ROOT_USER）：

cp backend/.env.example backend/.env

注意 .env.example 里没有 ENV= 行，生产部署需手工补上。生产环境必须设置：

ENV=production
SECRET_KEY=<随机字符串，至少 32 字节>
ADMIN_SECRET_KEY=<另一组随机字符串>
DATABASE_ENCRYPT_KEY=<数据库加密密钥>

可以使用以下命令生成密钥：

python -c "import secrets; print(secrets.token_urlsafe(32))"

Docker Compose

docker compose up -d

生产环境叠加：

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

默认会启动：前端（80）、后端（经 nginx 代理）、MinIO（9000/9001）。云同步依赖 MinIO，无需额外配置。

反向代理与 SSL

推荐使用 Nginx 或 Traefik 反代，并申请 Let's Encrypt 证书。生产拓扑二选一：

① Docker Compose 形态（推荐）：compose 起的前端容器内 nginx 监听 80 端口，已内置对 backend:8000 的反代，开箱即用。需要对外 HTTPS 时，外层反代直接指向前端容器的 80 端口即可，/api 由前端容器内的 nginx 负责转发，不要自己再拆路由。

② 自建 nginx 全托管：不用 compose 前端容器，由你的 nginx 终止 SSL 并整体反代到后端 uvicorn（8080 端口），完整参考仓库里的 nginx/grzhishiku.conf。关键点：/api 路径必须原样透传，不做路径重写——proxy_pass 末尾加斜杠会把 /api/v1/... 改写成 /v1/...，接口全 404。

自建 nginx 示例：

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        # 注意 proxy_pass 末尾不加斜杠，/api 原样透传给 uvicorn
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

备份

Docker 部署下 SQLite/图谱在 ./server-data/，原始文档与本地备份包在 ./server-data/uploads/。两者必须一起备份。PostgreSQL 形态还要导出数据库，并备份 minio-data 卷中的同步快照对象；只备份 server-data 不是完整恢复点。

更新

git pull
docker compose -f docker-compose.prod.yml up -d --build