使用文档生产部署

生产部署

配置服务器、HTTPS 反向代理和持久化存储,供团队访问 Feronavi。

运行环境

建议使用至少 4 核 CPU、8 GB 内存的主机。磁盘容量需要同时考虑数据库、附件、日志及备份,不应只按应用本身体积计算。默认从 GitHub Container Registry 拉取预构建镜像;仅源码构建需要访问依赖与基础镜像服务。

安装流程见快速开始。默认 Compose 配置使用 ghcr.io/feronavi/feronavi-app:latest、ghcr.io/feronavi/feronavi-db:16 预构建镜像,不需要在部署主机上编译产品。可在 .env 中设置 FERONAVI_VERSION=0.1.0 固定应用版本,并用 docker compose pull 获取镜像。

端口和访问路径

默认端口绑定为 127.0.0.1:3000。生产环境通过反向代理提供 HTTPS,不直接将应用端口开放到公网。

下面的域名 pm.example.com 是示例,替换为自己的域名,并将 DNS 指向服务器。

使用 Caddy 配置 HTTPS

当 Caddy 直接运行在与 Feronavi 相同的主机上时,可以使用:

pm.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:3000 {
        flush_interval -1
    }
    request_body {
        max_size 30MB
    }
}

公网域名满足证书签发条件时,Caddy 可以自动申请与续期证书。flush_interval -1 使流式响应及时传递。如果反向代理运行在容器或其他机器中,请按实际网络配置上游地址和可信代理网段。

使用 nginx

已有 nginx 的环境可以复用现有 TLS 配置。普通代理需要保留 Host 和转发协议;事件流入口需要关闭缓冲并使用更长的读取超时。

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_buffering off;
    proxy_read_timeout 300s;
}

location /api/v1/events {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Connection '';
    proxy_buffering off;
    proxy_read_timeout 3600s;
}

配置服务

配置项 用途
DB_PASSWORD 数据库密码,Compose 必须提供
APP_PORT 本机监听端口,默认 3000
TRUSTED_PROXY_CIDRS 应用信任的代理地址范围
VALKEY_MAXMEMORY 缓存内存上限,按机器资源规划

.env 用于 Compose 变量替换。新增应用环境变量时,还需要将其加入对应服务的 environment,只写进 .env 不会自动传入容器。

SMTP、模型和第三方集成通过管理界面配置。数据库与应用数据卷需要持久化。应用和 worker 使用同一版本以及同一数据目录。

上线检查

  1. 使用 HTTPS 完成登录和一次状态流转。
  2. 检查实时通知和知识助手流式输出是否及时到达。
  3. 上传附件并重新下载,确认代理大小限制合适。
  4. 检查审计记录能否识别真实客户端 IP。
  5. 创建并验证完整备份,见备份与升级。

输入关键词,搜索全部使用文档。