Ghostfolio 3.90.0 配置参数详解

目标：逐项讲清 Ghostfolio 3.90.0 全部环境变量参数——必填项、默认值、可实测验证的行为（安全头开关、端口陷阱、令牌盐语义、日志级别等），并给出生产配置模板。全部关键行为已在 Ubuntu 22.04 自托管实例实测验证（查询日期 2026-10-23）。

一、环境信息

• Ghostfolio：3.90.0（源码构建实例与 Docker Compose 实例各一套，行为一致）
• 操作系统：Ubuntu 22.04 LTS（x86_64）
• 依赖：PostgreSQL 14.24 / 15.19、Redis 6.0.16 / 8.10.2、Node.js v22.23.4
• 参数载体：纯环境变量（无独立应用配置文件），.env 文件 + EnvironmentFile（源码部署）或 env_file（Compose 部署）
• 参数依据：官方仓库 README「Supported Environment Variables」表（v3.90.0）+ 本文逐项实测

二、前置条件

有一套可运行的 Ghostfolio 实例即可逐项复现本文实验（源码构建部署见《Ubuntu 22.04 安装 Ghostfolio 3.90.0 指南》，Compose 部署见《Ghostfolio 3.90.0 Docker Compose 部署指南》）：

curl -s http://localhost:3333/api/v1/health

{"status":"OK"}

三、参数查看与修改方式

3.1 查看当前生效参数

Ghostfolio 无「运行时参数查询接口」（参数属进程环境），直接读进程环境或 .env：

docker compose -f /opt/ghostfolio/docker-compose.yml exec ghostfolio env | grep -E 'JWT|DATABASE|REDIS|PORT'

实测回显：

PORT=3333
DATABASE_URL=postgresql://ghostfolio:q1w2e3r4@postgres:5432/ghostfolio_db
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=q1w2e3r4
JWT_SECRET_KEY=8f4c1a9e7b2d5f3a6c0e9d1b4a7f2c5e8d0a3b6f9c1e4d7a0b3f6c9e2d5a8f1b

源码部署实例则 systemctl show ghostfolio -p Environment 或直接查看 /opt/ghostfolio/.env。

3.2 修改参数的两种生效路径

• Compose 部署：改 .env 后 docker compose up -d ghostfolio，Compose 检测到 env 变更自动重建容器（数据在 PostgreSQL，无损）；
• 源码部署：改 .env 后 systemctl restart ghostfolio（每行仅操作一个单元）。

⚠️ 注意：JWT_SECRET_KEY 与 ACCESS_TOKEN_SALT 之外的参数可随意改；这两个密钥的变更语义见 6.2 / 6.3。

四、参数总览

官方 README 参数表全量整理（Type/Default 为官方定义，"实测"列标注本文验证情况）：

OIDC 子参数（实验特性，仅在 ENABLE_FEATURE_AUTH_OIDC=true 时生效）：

解读：真正必填的只有两组——数据库（DATABASE_URL + POSTGRES_*）、Redis（REDIS_HOST/PORT/PASSWORD）与两个密钥（JWT_SECRET_KEY、ACCESS_TOKEN_SALT）；其余全部有默认值或可选。

五、核心参数分类详解

5.1 数据库参数组（DATABASE_URL / DIRECT_URL / POSTGRES_*）

• DATABASE_URL：应用运行时连接串，格式 postgresql://用户:密码@主机:5432/库名。Compose 内主机名写服务名（postgres），源码部署写 localhost；
• POSTGRES_USER/PASSWORD/DB：postgres 镜像首启初始化参数，只影响数据库容器，必须与 DATABASE_URL 中的凭据一致，否则迁移报 P1001（连接不可达）或认证失败；
• DIRECT_URL：Prisma 7 CLI（迁移与种子）专用直连串。Ghostfolio 的 Prisma 配置文件 .config/prisma.ts 实际取值逻辑为：

datasource: { url: process.env.DIRECT_URL ?? process.env.DATABASE_URL }

即不配 DIRECT_URL 时回退 DATABASE_URL。该参数的存在意义是「经连接池器（如 PgBouncer）部署时，迁移走直连、业务走池化」，单机直连 PostgreSQL 部署无需配置。

⚠️ Prisma 7 的 datasource 块不再内嵌 url，迁移必须能读到上述配置：源码部署时 /opt/ghostfolio/.config（内含 prisma.ts）必须复制进运行时目录，否则报 The datasource.url property is required in your Prisma config file（排障实录见安装指南 8.9）。

5.2 Redis 参数组（REDIS_HOST/PORT/PASSWORD/DB/TLS）

Ghostfolio 不提供 REDIS_URL 整串变量，按四个分项组装连接（另有 REDIS_TLS=false 控制加密）：

• REDIS_HOST/REDIS_PORT：主机与端口，Compose 内写服务名 redis + 6379；
• REDIS_PASSWORD：双向作用——既作应用认证密码，也是官方 compose 中 redis 服务 --requirepass 的来源（${REDIS_PASSWORD:?} 语法在缺失时拒绝启动 redis），改密码时两侧同源天然一致；
• REDIS_DB：逻辑库索引，默认 0；
• REDIS_TLS：托管 Redis（如云厂商 TLS 端点）时设 true。

Redis 故障行为实测：主机不可达时应用不退出，日志持续刷 ERROR [RedisCacheService] Error: connect ECONNREFUSED <host>:6379，行情缓存失效，健康接口仍返回 OK——但生产必须修复，行情刷新与部分后台任务依赖它。

5.3 密钥与认证参数组（JWT_SECRET_KEY / ACCESS_TOKEN_SALT / ENABLE_FEATURE_AUTH_TOKEN）

两个必填密钥的行为实测（本章最关键的实证部分）：

JWT_SECRET_KEY 缺失 → 启动即退出，实测完整回显：

 Missing environment variables:
    JWT_SECRET_KEY: undefined
================================

 Exiting with error code 1

ACCESS_TOKEN_SALT 语义：访问令牌（128 位 accessToken）以该盐哈希后入库比对。实测将盐改为 deadbeef… 后重建容器，用旧令牌调 POST /api/v1/auth/anonymous 返回：

{"statusCode":403,"message":"Forbidden"}

还原盐值重建后，同一旧令牌立即恢复登录成功（返回新 authToken）。结论：该盐参与凭据哈希，一旦有真实用户数据即不可更换；JWT_SECRET_KEY 仅影响 JWT 签名，更换会使已签发 JWT 全部过期，用户重新登录即可。

ENABLE_FEATURE_AUTH_TOKEN（默认 true）：关闭后 /api/v1/auth/anonymous 令牌登录入口禁用（配合 OIDC 场景）。

5.4 服务基础参数组（PORT / HOST / ROOT_URL）

• PORT（默认 3333）+ HOST（默认 0.0.0.0）：监听参数。实测 PORT=4444 后应用容器内 curl localhost:4444/api/v1/health 返回 {"status":"OK"}，但 compose 健康检查（硬编码 3333）失败、容器状态卡在 starting——改端口必须同步改健康检查或只改宿主映射；
• ROOT_URL（默认 http://0.0.0.0:3333）：用于生成 OIDC 回调等外部链接，反向代理/域名部署时设为 https://<域名>。

5.5 安全参数组（ENABLE_FEATURE_SECURITY_HEADERS / TRUST_PROXY）

ENABLE_FEATURE_SECURITY_HEADERS=true 实测响应头对比（GET /api/v1/health）：

开启时：

HTTP/1.1 200 OK
Content-Security-Policy: connect-src 'self' https://ghostfol.io;script-src 'self' 'unsafe-inline';script-src-attr 'self' 'unsafe-inline';style-src 'self' 'unsafe-inline';default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none'
X-Frame-Options: SAMEORIGIN

关闭时：两条头均不出现。说明：该开关启用 CSP 与 X-Frame-Options（禁止其他站点 iframe 嵌入），但 Strict-Transport-Security 需在反向代理层配置 HTTPS 时设置（官方 README 明确说明）。

TRUST_PROXY：Express 代理信任设置，Ghostfolio 用它识别限流的客户端 IP；经单个反向代理转发时设 TRUST_PROXY=1。

5.6 数据源参数组（API_KEY_COINGECKO_* / REQUEST_TIMEOUT）

Ghostfolio 行情数据源体系（官方自托管 FAQ 实查）：官方支持 COINGECKO、GHOSTFOLIO（付费 Premium 数据源，凭 API Key）、MANUAL、YAHOO 四种，其余实验性。实测 GET /api/v1/admin 返回的数据源清单（节选）：

{"dataProviders":[{"dataSource":"COINGECKO","isPremium":false,"name":"CoinGecko"},{"dataSource":"GHOSTFOLIO","isPremium":true,"name":"Ghostfolio"},{"dataSource":"MANUAL",...}]}

• API_KEY_COINGECKO_DEMO / API_KEY_COINGECKO_PRO：接入 CoinGecko 行情（加密货币价格），默认走 Yahoo 免费源；
• REQUEST_TIMEOUT（默认 3000ms）：数据源请求超时，弱网环境可调大；
• 网络受限环境（Yahoo 429 限流）的实测替代路径：自建 GF_ 前缀资产走 MANUAL 数据源（完整流程见部署指南 5.1）。

5.7 日志参数组（LOG_LEVELS）

LOG_LEVELS 接收 JSON 数组字符串。实测 LOG_LEVELS=["debug","error","log","warn"] 后应用日志出现 DEBUG 级明细：

10/23/2026, 7:32:21 AM   DEBUG [DataProviderService] Fetched 1 quote from cache in 0.003 seconds

排障时建议临时开 debug 观察 Redis 缓存命中与行情抓取；默认级别下仅 LOG/WARN/ERROR。

5.8 实验特性参数组（ENABLE_FEATURE_MCP）

ENABLE_FEATURE_MCP=true 会在 /mcp 暴露 Model Context Protocol 服务器端点（官方标注 experimental），供 AI 助手经 MCP 读写组合数据；3.90.0 的迁移记录中亦包含 MCP 权限域（20261017000000_added_account_update_scope_to_mcp_access），表明该能力处于活跃迭代期，生产启用需评估。

六、生产配置模板

适用场景：816GB 内存、SSD、个人/家庭自托管（15 用户），前置 Nginx/Caddy 做 TLS：

# /opt/ghostfolio/.env（生产模板）
NODE_ENV=production
PORT=3333
HOST=0.0.0.0
ROOT_URL=https://ghostfolio.example.com

POSTGRES_USER=ghostfolio
POSTGRES_PASSWORD=<生产强密码>
POSTGRES_DB=ghostfolio_db
DATABASE_URL=postgresql://ghostfolio:<生产强密码>@postgres:5432/ghostfolio_db

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=<生产强密码>
REDIS_DB=0

JWT_SECRET_KEY=<openssl rand -hex 32 生成>
ACCESS_TOKEN_SALT=<openssl rand -hex 32 生成，启用后永不再改>

TRUST_PROXY=1
ENABLE_FEATURE_SECURITY_HEADERS=true

要点：ROOT_URL 对齐反代域名；TRUST_PROXY=1 让限流按真实客户端 IP 计数；安全头开启；两个密钥由 openssl rand -hex 32 生成；数据库/Redis 密码独立强随机（演示环境统一 q1w2e3r4 仅为可复现）。生成命令实测：

openssl rand -hex 32

c73a1f0b9e4d2a8c5f1b6e0d3a7c4f9b2e8d1a5c0f6b3e9d2a8c4f1b7e0d3a6c9

七、常见问题（FAQ）

Q1：改了 .env 不生效？ 改 .env 后必须让进程重建：Compose 走 docker compose up -d ghostfolio（自动重建），systemd 走 systemctl restart ghostfolio。直接重启容器而不重建（Compose 检测不到 env 变更时）也会生效于下次重建，稳妥做法是用 up -d。

Q2：ACCESS_TOKEN_SALT 与 JWT_SECRET_KEY 能用同一个值吗？ 技术上可启动，但不建议：两者语义不同（盐用于凭据哈希永不可换；JWT 密钥可轮换），混用会把「可轮换」约束传染给「不可轮换」项。

Q3：PORT 改了之后健康检查一直失败？ 见 5.4 实测：健康检查脚本硬编码 3333。改 PORT 时同步改 compose healthcheck，或保持容器内 3333 只改宿主映射。

Q4：CAP_DROP 后 postgres 起不来？ 官方 compose 给 postgres 保留了 CHOWN/DAC_READ_SEARCH/FOWNER/SETGID/SETUID 五项能力（数据目录属主修正需要），删掉会启动失败；照抄官方配置即可。

Q5：自托管能拿到 API Key（数据源）功能吗？ 实测自托管 ADMIN 用户 permissions 不含 createApiKey，POST /api/v1/api-keys 返回 403——官方数据源 API Key 属 Ghostfolio Premium 订阅权益（FAQ 明确 GHOSTFOLIO 数据源 Premium 可用）；自托管免费层用 YAHOO/MANUAL/COINGECKO。

八、参考链接

• 官方环境变量总表（v3.90.0 README「Supported Environment Variables」）：https://github.com/ghostfolio/ghostfolio#self-hosting（查询日期 2026-10-23）
• 自托管 FAQ（数据源支持范围）：https://ghostfol.io/en/faq/self-hosting（内容同步于仓库 apps/client/src/app/pages/faq/self-hosting/，查询日期 2026-10-23）
• 部署实操：《Ubuntu 22.04 安装 Ghostfolio 3.90.0 指南》、《Ghostfolio 3.90.0 Docker Compose 部署指南》