运行环境
建议使用至少 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 使用同一版本以及同一数据目录。
上线检查
- 使用 HTTPS 完成登录和一次状态流转。
- 检查实时通知和知识助手流式输出是否及时到达。
- 上传附件并重新下载,确认代理大小限制合适。
- 检查审计记录能否识别真实客户端 IP。
- 创建并验证完整备份,见备份与升级。