Bigcapital v0.25.44 配置参数详解
Bigcapital v0.25.44 全量环境变量详解：.env 加载优先级与修改方式、30 余个参数的分类说明与实测验证（注册限制、端口覆盖、多租户库、限流、Gotenberg、S3/Garage、ClickHouse 等），附生产配置模板。
Bigcapital v0.25.44 配置参数详解
Bigcapital Server（NestJS）的全部行为配置通过环境变量注入，官方在源码包根目录提供 .env.example 模板（v0.25.44 共 60 余行注释与变量），涵盖应用安全、数据库、注册控制、限流、PDF 导出、对象存储、银行连接、支付订阅、分析存储与通知等模块。本文基于 v0.25.44 源码与实测环境逐类拆解这些参数：加载优先级、修改方式、默认值、取值约束与生效验证。
安装路径与环境准备见 《Ubuntu 22.04 安装 Bigcapital v0.25.44 指南》 与 《Bigcapital v0.25.44 Docker Compose 部署指南》；软件定位见 《Bigcapital v0.25.44 介绍与选型指南》。
本文参数默认值与注释均摘自 v0.25.44 官方
.env.example（2026-10-22 实测环境核对）；标注「实测」的条目均在真实安装环境中验证过生效效果。
一、环境信息
| 项目 | 说明 |
|---|---|
| 软件 | Bigcapital v0.25.44（官方发布源码包） |
| 服务器 | Ubuntu 22.04.5 LTS，12 核 31 GiB |
| 运行形态 | 源码直装：Node.js v18.20.8 + MariaDB 10.6.23 + Redis 6.0.16 |
| 配置文件 | /opt/bigcapital/.env（实测环境路径） |
| 模板文件 | /opt/bigcapital/.env.example |
二、前置条件
- 已按 《Ubuntu 22.04 安装 Bigcapital v0.25.44 指南》 或 Compose 方式完成部署，Server 可启动。
- 具备服务器文件编辑权限与 MariaDB 访问权限（部分参数与数据库账号强关联）。
- 了解 Bigcapital 双库模型：固定系统库 + 每组织一个租户库（库名 = 前缀 + 组织 ID），多个参数围绕该模型设计，见 5.2。
三、参数查看与修改方式
3.1 配置文件位置与加载优先级
Server 与 CLI 都通过 NestJS ConfigModule 按固定顺序加载两处 .env（源码 packages/server/src/common/config/env.ts 实测摘录）：
const SERVER_ENV_FILE_PATH = join(__dirname, '../../../.env');
const ROOT_ENV_FILE_PATH = join(__dirname, '../../../../../.env');
export const ENV_FILE_PATHS = [SERVER_ENV_FILE_PATH, ROOT_ENV_FILE_PATH];
即：先找 packages/server/.env，再找源码根目录 .env，列表中靠前的文件优先。实测环境只在根目录创建 .env（安装指南 4.7 的做法），因此根目录 .env 是唯一生效文件；若两处都存在，同一变量以 packages/server/.env 中的值为准。
3.2 查看当前生效配置
grep -vE '^#|^$' /opt/bigcapital/.env
实测回显（关键行，口令类已按演示值展示）：
APP_JWT_SECRET=ptsviuCqijT6S/3v4lM+ueLFJZiVwANRwmcZ54nWmVkLpTNrZlUK9ZDKPCnksZPc
DB_HOST=127.0.0.1
DB_USER=bigcapital
DB_PASSWORD=q1w2e3r4
DB_CHARSET=utf8
SYSTEM_DB_NAME=bigcapital_system
TENANT_DB_NAME_PERFIX=bigcapital_tenant_
BASE_URL=http://localhost
SIGNUP_DISABLED=false
3.3 修改方式与生效条件
.env 修改后必须重启 Server 进程才生效（源码直装为 systemctl restart bigcapital-server，Compose 部署为重建 server 服务）。本文的参数验证均采用「修改 → 重启 → 复测」流程，例如注册开关的实测见 5.3。
启动时的环境变量可以覆盖 .env 之外的运行参数，典型如监听端口：.env 中无需写 PORT，直接以 PORT=3100 前缀启动即可变更监听端口（离线部署验证时实测生效，服务改听 3100 端口并正常响应 401 认证保护）。
3.4 配置错误的表现
数据库类参数配置错误时，Server 启动后首次访问接口即报数据库连接失败；迁移类 CLI 则直接报错退出（如系统库不存在时的 ER_BAD_DB_ERROR，见安装指南 9.3）。APP_JWT_SECRET 属于必需项，留空会导致登录令牌不可用。
四、参数总览
按 .env.example 的分组顺序汇总（默认值列即模板中的出厂值，空串表示未配置）：
| 分类 | 变量 | 默认值 | 说明 |
|---|---|---|---|
| 应用安全 | APP_JWT_SECRET | 空（必填） | 登录令牌签名密钥，模板建议 openssl rand -base64 48 生成 |
| 数据库 | DB_HOST / DB_USER / DB_PASSWORD | localhost / bigcapital / bigcapital | MariaDB 连接 |
| 数据库 | DB_ROOT_PASSWORD | root | root 口令声明（源码直装不使用） |
| 数据库 | DB_CHARSET | utf8 | 连接字符集 |
| 数据库 | SYSTEM_DB_NAME | bigcapital_system | 系统库名 |
| 数据库 | SYSTEM_DB_USER / SYSTEM_DB_PASSWORD / SYSTEM_DB_CHARSET | 注释状态 | 系统库连接的独立覆盖项 |
| 数据库 | TENANT_DB_NAME_PERFIX | bigcapital_tenant_ | 租户库库名前缀 |
| 数据库 | TENANT_DB_HOST / TENANT_DB_USER / TENANT_DB_PASSWORD / TENANT_DB_CHARSET | 注释状态 | 租户库连接的独立覆盖项 |
| 应用 | BASE_URL | http://example.com | 对外访问地址 |
| 应用 | PUBLIC_PROXY_PORT / PUBLIC_PROXY_SSL_PORT | 80 / 443 | 对外代理端口声明 |
| 注册控制 | SIGNUP_DISABLED | false | 关闭注册入口 |
| 注册控制 | SIGNUP_ALLOWED_DOMAINS / SIGNUP_ALLOWED_EMAILS | 空 | 注册邮箱白名单（域名/完整地址） |
| 注册控制 | SIGNUP_EMAIL_CONFIRMATION | false | 注册后需邮件确认 |
| 限流 | THROTTLE_GLOBAL_TTL / THROTTLE_GLOBAL_LIMIT | 60000 / 300 | 全局限流：60 秒窗口 300 次 |
| 限流 | THROTTLE_AUTH_TTL / THROTTLE_AUTH_LIMIT | 60000 / 30 | 认证接口限流：60 秒窗口 30 次 |
| PDF 导出 | GOTENBERG_URL / GOTENBERG_DOCS_URL | http://localhost:9000 等 | Gotenberg 服务地址 |
| 汇率 | EXCHANGE_RATE_SERVICE | open-exchange-rate | 汇率服务商标识 |
| 汇率 | OPEN_EXCHANGE_RATE_APP_ID | 空 | Open Exchange Rates 应用 ID |
| 银行连接 | PLAID_ENV | sandbox | Plaid 环境（sandbox 或 development） |
| 银行连接 | PLAID_CLIENT_ID / PLAID_SECRET / PLAID_LINK_WEBHOOK / PLAID_CLIENT_NAME | 空 | Plaid 凭据与应用名 |
| 支付 | STRIPE_PAYMENT_SECRET_KEY 等 5 项 | 空 | Stripe 支付（sk_/pk_/ca_/whsec_ 前缀密钥与回调） |
| 订阅 | LEMONSQUEEZY_API_KEY / LEMONSQUEEZY_STORE_ID / LEMONSQUEEZY_WEBHOOK_SECRET | 空 | Lemon Squeezy 订阅计费 |
| 对象存储 | S3_REGION / S3_ENDPOINT / S3_BUCKET | garage / http://garage:3900 / bigcapital | S3 兼容存储（模板按 Garage 预填） |
| 对象存储 | S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY | 空 | S3 访问密钥 |
| 对象存储 | S3_FORCE_PATH_STYLE | true | Garage 等 S3 兼容存储需 path-style |
| 对象存储 | GARAGE_RPC_SECRET / GARAGE_ADMIN_TOKEN | 空 | Garage 集群密钥（RPC 密钥需 64 位十六进制） |
| 对象存储 | GARAGE_LOCAL_ZONE / GARAGE_CAPACITY | 注释状态（dc1 / 10G） | Garage 节点布局参数 |
| 分析 | POSTHOG_API_KEY / POSTHOG_HOST | 空 | PostHog 埋点 |
| 分析 | CLICKHOUSE_ENABLED | false | 是否启用 ClickHouse 分析库 |
| 分析 | CLICKHOUSE_HOST / CLICKHOUSE_PORT / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD / CLICKHOUSE_DATABASE | localhost / 8123 / default / 空 / bigcapital_analytics | ClickHouse 连接 |
| 通知 | TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN / TWILIO_FROM_NUMBER | 空 | Twilio 短信全局回退 |
| 邮件 | MAIL_HOST / MAIL_USERNAME / MAIL_PASSWORD / MAIL_PORT / MAIL_SECURE / MAIL_FROM_NAME / MAIL_FROM_ADDRESS | 空 | SMTP 出站邮件 |
| 自动更新 | AUTO_UPDATE_INTERVAL | 3600 | 自动更新轮询秒数（Compose 部署形态使用） |
五、核心参数分类详解
5.1 应用与安全
APP_JWT_SECRET（必填）：登录 JWT 的签名密钥，生产环境必须用 openssl rand -base64 48 生成独立随机值。实测环境取值即按该方式生成的 64 位串（见 3.2 回显）。更换该密钥后所有已登录令牌立即失效，用户需重新登录——轮换时应安排在低峰期。
PORT：Server 监听端口，.env.example 未列出但源码固定支持（启动逻辑为 process.env.PORT ?? 3000）。实测以 PORT=3100 前缀启动后服务改听 3100；默认 3000。
BASE_URL：系统对外访问地址，用于拼装对外链接（邮件确认、回调地址等）。实测环境配置为 http://localhost；生产环境应改为实际 IP 或域名并保持与 Nginx/代理的对外协议一致。
PUBLIC_PROXY_PORT / PUBLIC_PROXY_SSL_PORT：对外代理端口声明（默认 80/443），供需要了解外部端口形态的功能使用，一般保持默认。
5.2 数据库连接与多租户库
Bigcapital 采用「一个系统库 + 每组织一个租户库」的双库模型：系统库 bigcapital_system 存用户、组织登记与全局迁移记录；租户库 bigcapital_tenant_<组织ID> 存该组织的账套数据（实测单组织初始化后含 70 张表）。
基础连接：DB_HOST、DB_USER、DB_PASSWORD、DB_CHARSET 为系统库与租户库共用。实测环境指向本机 127.0.0.1，专用账号 bigcapital 只授予 bigcapital% 前缀库的权限即可满足「程序运行时自动建租户库」的需要（实测组织初始化成功建库）。
前缀参数 TENANT_DB_NAME_PERFIX：决定租户库命名，实测默认值下租户库名为 bigcapital_tenant_4f65c9t9g6mvjujvi3（组织 ID 拼接）。变量名中 PERFIX 为项目原始拼写，需照抄使用，写成 PREFIX 不会生效。
独立覆盖项：SYSTEM_DB_* 与 TENANT_DB_* 系列允许系统库与租户库使用不同的主机/账号/字符集（例如租户库放在独立实例上），模板中默认注释（即不启用，回落到 DB_* 共用值）。
DB_ROOT_PASSWORD：声明 root 口令，供官方打包形态的初始化流程使用；源码直装路径不读取该项。
5.3 注册与访问控制
SIGNUP_DISABLED：设为 true 后注册接口被禁。实测验证：改为 true 并重启后，调用注册接口返回：
{"errors":[{"statusCode":400,"type":"SIGNUP_RESTRICTED_NOT_ALLOWED","message":"The given email address format is not allowed to signup."}]}
HTTP 状态码 400。改回 false 并重启后恢复。适用于「管理员建号制」的内部部署。
SIGNUP_ALLOWED_DOMAINS / SIGNUP_ALLOWED_EMAILS：注册白名单，前者按邮箱域（如 example.com），后者按完整地址，逗号分隔。未配置时不限制。
SIGNUP_EMAIL_CONFIRMATION：设为 true 时注册后需经邮件确认才能登录，依赖 5.11 的邮件参数正确配置；未配置邮件时保持 false，否则新用户无法完成首次登录。
5.4 API 限流
THROTTLE_GLOBAL_TTL/THROTTLE_GLOBAL_LIMIT 作用于全部接口，THROTTLE_AUTH_TTL/THROTTLE_AUTH_LIMIT 仅作用于认证路由，出厂值为 60 秒窗口内全局 300 次、认证 30 次。模板注释明确提示：批量导入或脚本化数据迁移时，可临时调高 THROTTLE_GLOBAL_LIMIT，完成后调回。
5.5 PDF 导出（Gotenberg）
GOTENBERG_URL 指向 Gotenberg 服务（发票/报表等 PDF 导出的渲染引擎），GOTENBERG_DOCS_URL 为 Server 侧可被 Gotenberg 回取的文档地址。模板区分了生产形态（http://gotenberg:3000）与开发形态（http://localhost:9000）。实测源码直装环境未部署 Gotenberg、该项保持指向但不影响登录与记账核心功能，仅 PDF 导出相关操作不可用；部署 Compose 全家桶时该服务由官方模板自带（见 《Bigcapital v0.25.44 Docker Compose 部署指南》）。
5.6 汇率服务
EXCHANGE_RATE_SERVICE 选择汇率数据源（默认 open-exchange-rate），OPEN_EXCHANGE_RATE_APP_ID 填该服务的应用 ID。不配置时涉及多币种换算的功能使用离线默认汇率，配置后自动拉取实时汇率。
5.7 对象存储 S3/Garage
附件与单据文件通过 S3 兼容接口存储，官方模板按自托管 Garage 预填：S3_REGION=garage、S3_ENDPOINT=http://garage:3900、S3_BUCKET=bigcapital、S3_FORCE_PATH_STYLE=true（Garage 要求 path-style 访问）。S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY 由 Garage 初始化输出。实测 Compose 部署时按官方流程初始化 Garage 并回填密钥，附件上传链路打通（初始化细节与命令差异见 Compose 指南 FAQ）。GARAGE_RPC_SECRET 要求 64 位十六进制随机串（openssl rand -hex 32 生成），GARAGE_ADMIN_TOKEN 为管理口令。
5.8 银行连接 Plaid
PLAID_ENV 支持 sandbox 与 development（模板注释附官方说明链接），PLAID_CLIENT_ID/PLAID_SECRET 为 Plaid 控制台签发的凭据，PLAID_LINK_WEBHOOK 为回调地址，PLAID_CLIENT_NAME 为用户在 Plaid Link 界面看到的应用名（最长 30 字符，缺省 Bigcapital）。该模块面向北美银行网络，国内部署通常不启用。
5.9 支付与订阅
STRIPE_PAYMENT_* 五项（sk_ 私钥、pk_ 公钥、ca_ 客户端 ID、whsec_ 回调签名密钥、回调跳转地址）用于 Stripe 在线收款；模板注释给出了回调端点 URL 拼装方式与需勾选的事件（checkout.session.completed、account.updated）。LEMONSQUEEZY_* 三项用于 Lemon Squeezy 订阅计费。两者均为可选商业化组件，自用部署留空即可。
5.10 分析存储 ClickHouse
CLICKHOUSE_ENABLED=false 时组织级财务汇总由 MariaDB 计算；设为 true 后汇总改从 ClickHouse 读取（库 bigcapital_analytics）。模板注释明确两点约束：生产模板要求非空 CLICKHOUSE_PASSWORD（为空拒绝启动）；CLICKHOUSE_HOST 在生产模板中被固定为 clickhouse 服务名，该变量实际只在开发形态生效。启用前需先部署 ClickHouse 24.8 系列并完成对应初始化。
5.11 通知与邮件
MAIL_* 系列：SMTP 出站邮件（注册确认、邀请、通知）。MAIL_SECURE 控制是否使用 TLS 直连（465 端口场景设 true），MAIL_FROM_NAME/MAIL_FROM_ADDRESS 为发件人显示。实测未配置时注册登录流程正常，仅邮件类功能不可用。
TWILIO_* 系列：Twilio 短信通知的全局回退配置（账号 SID、令牌、发送号码），可选。
六、生产配置模板
场景一：源码直装最小生产配置（本文实测环境同款结构，资源建议 2 核 4 GiB 起）：
APP_JWT_SECRET=<openssl rand -base64 48 生成>
DB_HOST=127.0.0.1
DB_USER=bigcapital
DB_PASSWORD=<强口令>
DB_CHARSET=utf8
SYSTEM_DB_NAME=bigcapital_system
TENANT_DB_NAME_PERFIX=bigcapital_tenant_
BASE_URL=http://<服务器IP或域名>
PUBLIC_PROXY_PORT=80
PUBLIC_PROXY_SSL_PORT=443
SIGNUP_DISABLED=false
SIGNUP_ALLOWED_DOMAINS=
SIGNUP_ALLOWED_EMAILS=
SIGNUP_EMAIL_CONFIRMATION=false
THROTTLE_GLOBAL_TTL=60000
THROTTLE_GLOBAL_LIMIT=300
THROTTLE_AUTH_TTL=60000
THROTTLE_AUTH_LIMIT=30
场景二：全功能部署追加项（PDF 导出、附件存储、实时汇率；磁盘需为附件预留空间，ClickHouse 启用另需独立资源）：
GOTENBERG_URL=http://<gotenberg地址>:3000
GOTENBERG_DOCS_URL=http://<server地址>/public/
S3_REGION=garage
S3_ENDPOINT=http://<garage地址>:3900
S3_BUCKET=bigcapital
S3_ACCESS_KEY_ID=<初始化输出>
S3_SECRET_ACCESS_KEY=<初始化输出>
S3_FORCE_PATH_STYLE=true
GARAGE_RPC_SECRET=<openssl rand -hex 32 生成>
GARAGE_ADMIN_TOKEN=<自定义管理口令>
EXCHANGE_RATE_SERVICE=open-exchange-rate
OPEN_EXCHANGE_RATE_APP_ID=<服务申请>
MAIL_HOST=<SMTP服务器>
MAIL_PORT=465
MAIL_SECURE=true
MAIL_USERNAME=<发件账号>
MAIL_PASSWORD=<发件口令>
MAIL_FROM_NAME=Bigcapital
MAIL_FROM_ADDRESS=<发件地址>
修改任何参数后重启 Server 并按第三章流程复测。
七、常见问题
7.1 TENANT_DB_NAME_PERFIX 的拼写
变量名中的 PERFIX 是项目原始拼写（正确英文应为 PREFIX），.env 与模板均如此，必须照抄；实测改写为 PREFIX 后程序读取的仍是 TENANT_DB_NAME_PERFIX，租户库前缀不会变化。
7.2 修改了 .env 但行为没变化
两个常见原因：其一，未重启 Server（所有 .env 参数均需重启生效）；其二，packages/server/.env 与根目录 .env 同时存在时前者优先（见 3.1），确认没有旧文件残留覆盖。排查命令：
ls -l /opt/bigcapital/.env /opt/bigcapital/packages/server/.env 2>&1
7.3 更换 APP_JWT_SECRET 后用户全部掉线
属预期行为：旧令牌基于旧密钥签名，换密钥后校验全部失败。轮换密钥前通知用户，或安排在非工作时段执行。
7.4 注册口令长度报错
注册接口强制口令不少于 10 位，实测 8 位口令返回 password must be longer than or equal to 10 characters（HTTP 400）。该行为不受 .env 参数控制，规划演示账号时需按 10 位以上设置（本文全系列文档统一用 q1w2e3r4t6）。
7.5 SIGNUP_EMAIL_CONFIRMATION=true 后新用户无法登录
确认邮件依赖 MAIL_* 参数；SMTP 未配置或配置错误时确认邮件发不出去，新用户停留在未确认状态。先按 5.11 打通邮件链路，或将该参数改回 false。
八、参考链接
- Bigcapital 官方仓库：https://github.com/bigcapitalhq/bigcapital
- v0.25.44 发布页：https://github.com/bigcapitalhq/bigcapital/releases/tag/v0.25.44
- 站内相关文档：
- 《Bigcapital v0.25.44 介绍与选型指南》——软件定位与选型
- 《Ubuntu 22.04 安装 Bigcapital v0.25.44 指南》——源码直装全流程
- 《Bigcapital v0.25.44 Docker Compose 部署指南》——整套部署形态与 Garage 初始化
- 《Bigcapital v0.25.44 常用 CLI 命令与工具详解》——迁移/种子等 CLI 用法