Ever Gauzy 111.48.2 配置参数详解

目标：系统梳理 Ever Gauzy v111.48.2 的配置参数体系——官方 .env.sample 定义的全部 418 个变量的分组、默认值与生效方式，并给出镜像部署实测的运行时环境变量核验方法与生产配置模板。全部默认值取自源码仓库 ever-gauzy v111.48.2 标签的 .env.sample（commit 5b3f778），运行时实测值取自 Ubuntu 22.04 镜像部署环境（docker compose exec 导出核对，实测注入 54 个变量）。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Ever Gauzy：v111.48.2（源码仓库 tag v111.48.2，commit 5b3f778e1d12f21992b39b42218fd2fd354c21d6）
• 数据库：PostgreSQL 17（生产推荐；官方默认 better-sqlite3 仅评估用）
• 部署形态：Docker Compose 三服务（api / webapp / db），API 端口 8144、Web 端口 8147
• 参数基线文件：源码仓库根目录 .env.sample（1029 行，定义 418 个变量）

二、前置条件

1. 已完成部署并拿到一套可运行环境（镜像部署见 《Ever Gauzy 111.48.2 Docker Compose 部署指南》，源码安装见 《Ubuntu 22.04 安装 Ever Gauzy 111.48.2 指南》）。本文所有查看/修改操作在该环境上实测。
2. 理解 Gauzy 配置的三层来源：默认值（编译进代码）→ .env 文件（源码部署）或 Compose environment（镜像部署）→ 平台界面设置（存数据库，优先级最高）。本文聚焦第二层。

三、参数查看与修改方式

3.1 镜像部署：查容器实际生效值

以部署目录（含 docker-compose.yml）为工作目录，导出 API 容器运行时环境变量并统计：

cd /opt/ever-gauzy/stack
docker compose exec api env | sort

实测输出（节选，首尾）：

ALLOW_SUPER_ADMIN_ROLE=true
API_BASE_URL=http://localhost:8144
APP_NAME=Gauzy
...
THROTTLE_ENABLED=true
THROTTLE_LIMIT=60000
THROTTLE_TTL=60000
TRUST_PROXY=1

docker compose exec api env | wc -l

实测输出：

54

实测该部署形态共注入 54 个运行时变量，覆盖应用标识、数据库、安全密钥、种子账号、限流、代理等核心域，其余 360 余个变量保持官方默认。Web 前端容器同样可查：docker compose exec webapp env | sort。

3.2 源码部署：查 .env 与 systemd 生效值

源码部署时配置在仓库根目录 .env（从 .env.sample 复制修改而来）。查看某组参数：

grep -E '^(DB_|JWT_)' /opt/ever-gauzy/.env

实测输出（示例环境）：

DB_ORM=typeorm
DB_TYPE=postgres
DB_HOST=localhost
DB_PORT=5432
DB_NAME=gauzy
DB_USER=postgres
DB_PASS=q1w2e3r4
JWT_SECRET=<openssl rand -hex 64 生成的 128 位十六进制串>

systemd 托管时以服务单元实际注入为准：

systemctl show ever-gauzy-api --property=Environment

实测输出（示例）：

Environment=NODE_ENV=production API_PORT=3000 DB_TYPE=postgres

3.3 运行时核验：不进服务器也能确认关键参数

两个公开端点可直接反映配置生效情况。版本端点反映 GAUZY_APP_VERSION/GAUZY_APP_COMMIT 的注入值：

curl -s http://localhost:8144/api/version

实测输出：

{"name":"api","version":"v111.48.2","commit":"5b3f778e1d12f21992b39b42218fd2fd354c21d6"}

健康端点的返回细节反映缓存参数效果（REDIS_ENABLED=false 时缓存类型为进程内存）：

curl -s http://localhost:8144/api/health | head -c 300

实测输出：

{"status":"ok","info":{"database":{"status":"up"},"storage":{"status":"up"},"cache":{"status":"up","cacheType":"memory"}},...

3.4 修改参数的正确姿势

• 镜像部署：改项目目录 .env → docker compose up -d 重建受影响容器 → 用 3.1/3.3 方法核验。
• 源码部署：改 .env → systemctl restart ever-gauzy-api（服务名按实际单元）→ 核验。
• ⚠️ 平台「设置」界面保存的值写数据库，运行时优先于环境变量；排查「改了环境变量没生效」时先检查界面上是否覆盖过同名设置。

四、参数总览

官方 .env.sample 共定义 418 个变量，按域分组统计如下（组名即 §5 分节）：

💡 说明：分组数为按 .env.sample 注释分节归并的近似值，总计 418 项。生产自托管只需改前 11 组中的二三十个变量，其余保持默认。

五、核心参数分类详解

5.1 应用标识与地址

⚠️ 注意：API_BASE_URL/CLIENT_BASE_URL 是浏览器视角地址。镜像部署改端口时这两项必须同步（实测 8144/8147），否则前端请求与邮件链接全部指错。

5.2 运行模式

实测效果：DEMO=false + NODE_ENV=production 下，本环境首启只产生了 admin@ever.co 一个超级管理员账号（实测登录成功），没有灌入演示业务数据。

5.3 数据库连接（PostgreSQL 依赖链）

实测效果：DB_TYPE=postgres 首启后 ORM 自动完成建表，实测生成 290 张业务表（information_schema 查询 public schema 计数），全程无需手工迁移命令——这是 Gauzy PostgreSQL 依赖链的关键行为：驱动选好、连接给对，建表交给首启。

💡 技术拓展：DB_TYPE 的四个可选引擎如何选——

引擎	特点	适用场景
better-sqlite3（官方默认）	单文件零部署，无并发写优势	本机试用/评估
postgres	企业级并发与事务，官方生产推荐	团队生产部署
mysql	生态通用，功能对齐 PG	已有 MySQL 运维体系
sqlite	轻量文件库，兼容旧路径	极简单机

本文/官方生产形态采用 postgres，多用户并发的时间追踪写入场景必须走服务端数据库。

5.4 安全密钥与令牌

生产强校验（官方明文设计）：NODE_ENV=production 且 DEMO!=true 时，四个密钥任一为空或保留公开默认值，API 拒绝启动；非生产环境留空时 API 会对本进程随机生成临时密钥（重启即失效，所有已发令牌作废）。生成方式 openssl rand -hex 64，多实例部署必须共享同一组值。

5.5 种子账号与登录锁定

⚠️ 注意：三个演示账号口令是自托管环境的「首启种子」，DEMO=false 时生效的主要是超级管理员对；生产上线第一步就应登录界面改掉 q1w2e3r4。

5.6 限流与代理

实测效果：本环境健康检查、登录、业务接口均在限流默认阈值内正常响应。公开部署且前面有 nginx 时保持 TRUST_PROXY=1；若无反代直连，应改为 TRUST_PROXY=0，否则客户端可伪造 X-Forwarded-For 绕过限流桶。

5.7 邮件 SMTP

实测效果：本环境未配置 SMTP 认证，平台核心功能（登录、任务、时间追踪）不受影响，仅邮箱验证/邀请/找回密码等邮件流不可用——这是自托管评估阶段的常见形态，上生产必须补齐。

5.8 文件存储

实测效果：FILE_PROVIDER=LOCAL 时上传文件落本地目录（镜像部署 bind mount 到 /srv/gauzy/apps/api/public，实测本环境该目录随上传增长；源码部署落 apps/api/public）。

5.9 缓存与队列

实测效果：REDIS_ENABLED=false 时健康检查返回 "cache":{"status":"up","cacheType":"memory"}（进程内存缓存，实测输出见 §3.3）。单实例部署内存缓存够用；多实例/横向扩展必须开 Redis，否则会话与缓存不共享。

5.10 国际化默认值

5.11 功能开关（FEATURE_*）

.env.sample 定义了约 74 个 FEATURE_* 布尔开关，全部默认 true 的包括仪表盘、时间追踪、发票、收入/支出/支付、提案/管道、任务（个人/团队/项目）、员工/候选人/面试、目标/报表、组织设备/库存/标签/供应商、角色权限、SMTP、导入导出等；两个例外默认 false：

实测效果：默认配置下本环境的功能清单齐全（任务/费用/发票接口全部可调通，实测见 API 使用篇）；把某项设为 false 后重启，对应菜单与接口即被隐藏/关闭。

5.12 第三方登录与集成

78 个集成变量覆盖四大类，生产按需取用：

⚠️ 注意：CALLBACK_URL 系列默认值都是 http://localhost:3000/...，配置任一 OAuth 时要同步改成 API_BASE_URL 对应的公网回调地址。

5.13 可观测与统计

实测效果：本环境全部保持默认关闭，API 日志无任何外发上报行为。

5.14 AI 能力

实测效果：未配任何密钥时 AI 助手入口无密钥可用（不报错、仅不可用），其余功能正常。

5.15 MCP 服务

六、生产配置模板

以下模板面向「50 人以内团队、4 vCPU / 8 GiB 内存 / 100 GB SSD、公网域名 + nginx 反代」的典型自托管场景，只列需要改动/确认的变量（其余保持 .env.sample 默认）：

# ---- 运行模式 ----
NODE_ENV=production
DEMO=false
IS_DOCKER=true
ALLOW_SUPER_ADMIN_ROLE=true

# ---- 地址（换成真实域名） ----
API_BASE_URL=https://gauzy.example.com
CLIENT_BASE_URL=https://gauzy.example.com

# ---- 数据库（PostgreSQL 必选） ----
DB_TYPE=postgres
DB_ORM=typeorm
DB_HOST=db
DB_PORT=5432
DB_NAME=gauzy
DB_USER=gauzy
DB_PASS=<openssl rand -base64 24 生成>
DB_SSL_MODE=false
DB_POOL_SIZE=40

# ---- 安全密钥（四把全部重新生成，多实例共享） ----
JWT_SECRET=<openssl rand -hex 64>
JWT_REFRESH_TOKEN_SECRET=<openssl rand -hex 64>
JWT_VERIFICATION_TOKEN_SECRET=<openssl rand -hex 64>
EXPRESS_SESSION_SECRET=<openssl rand -hex 64>

# ---- 首启种子账号（首登后立即在界面改密） ----
DEMO_SUPER_ADMIN_EMAIL=admin@example.com
DEMO_SUPER_ADMIN_PASSWORD=<强口令>

# ---- 限流与代理（nginx 反代后） ----
THROTTLE_ENABLED=true
THROTTLE_TTL=60000
THROTTLE_LIMIT=20000
TRUST_PROXY=1

# ---- 邮件（生产必配） ----
MAIL_FROM_ADDRESS=gauzy@example.com
MAIL_HOST=smtp.example.com
MAIL_PORT=465
MAIL_USERNAME=gauzy@example.com
MAIL_PASSWORD=<SMTP 口令>

# ---- 国际化 ----
DEFAULT_CURRENCY=CNY
DEFAULT_COUNTRY=CN

# ---- 文件存储（小团队本地盘，大文件走 S3） ----
FILE_PROVIDER=LOCAL

# ---- 功能策略 ----
FEATURE_EMAIL_VERIFICATION=true
FEATURE_OPEN_STATS=false

要点：数据库独立强口令、四把密钥全部重生成、API_BASE_URL/CLIENT_BASE_URL 换域名、限流阈值按团队规模收紧到 THROTTLE_LIMIT=20000、邮件必配、FEATURE_EMAIL_VERIFICATION 打开。

七、常见问题

Q1：改了 .env 但平台行为没变？ 三层配置优先级是「界面设置（数据库）> 环境变量 > 代码默认值」。先在平台「设置」界面确认没有覆盖同名项；其次确认修改后执行了 docker compose up -d（镜像部署）或重启了服务（源码部署）——环境变量只在进程启动时读取。

Q2：API 起不来，提示密钥校验失败？ 生产模式（NODE_ENV=production 且 DEMO!=true）下 JWT_SECRET、JWT_REFRESH_TOKEN_SECRET、JWT_VERIFICATION_TOKEN_SECRET、EXPRESS_SESSION_SECRET 任一为空或为公开默认值都会被拒绝。用 openssl rand -hex 64 逐个生成后重启。

Q3：DB_TYPE 从 sqlite 换成 postgres 后老数据还在吗？ 不在。两种引擎的数据互不相通，切换前先用 pg_dump/sqlite 导出。Gauzy 无内置跨引擎迁移命令，正式环境一开始就定好 DB_TYPE=postgres 是最省事的做法。

Q4：多实例部署要注意哪些参数？ 必须：REDIS_ENABLED=true 并共享同一 Redis（内存缓存各进程独立会导致会话漂移）；四把安全密钥全实例一致；THROTTLE_TRUST_CF_CONNECTING_IP/TRUST_PROXY 按实际接入层配置，否则限流按代理 IP 计桶。

Q5：FEATURE_* 开关和界面里的「功能」冲突吗？ 环境变量是全局基线，界面设置按租户覆盖。排障顺序：先查租户级设置，再查环境变量，最后查代码默认值。

Q6：如何确认某个变量真的被进程读到了？ 镜像部署 docker compose exec api env | grep <名称>；源码部署 cat /proc/$(pgrep -f main.js)/environ | tr '\0' '\n' | grep <名称>。两个命令看到的都是进程启动那一刻的真实值。

八、参考链接

• 官方配置基线：源码仓库 https://github.com/ever-co/ever-gauzy 根目录 .env.sample（tag v111.48.2）
• 官方文档（部署/环境变量）：https://docs.ever.co/
• 平台内部署篇：《Ever Gauzy 111.48.2 Docker Compose 部署指南》
• 平台内认知篇：《Ever Gauzy 111.48.2 介绍与选型指南》