Actual Budget 同步服务器配置完全指南：config.json 与全部环境变量解析

Actual Budget 同步服务器配置完全指南config.json 与全部环境变量解析【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actualActual BudgetActual是一款本地优先local-first的个人财务管理应用其自托管同步服务器sync-server负责存储预算数据、处理多端同步与认证。本文将围绕服务器启动时的配置文件机制完整讲解config.json的所有可用键、对应的环境变量、它们之间的优先级关系并结合仓库源码说明每一项配置在底层是如何被解析与生效的。读完本文你将能独立完成一台 Actual 同步服务器的初始化、HTTPS 启用、上传限制调整、登录方式切换与反向代理场景下的信任配置。配置的加载顺序与优先级Actual 同步服务器在启动时会读取一个可选的config.json文件其查找位置遵循以下规则源码见 packages/sync-server/src/load-config.js如果设置了ACTUAL_CONFIG_PATH环境变量则直接读取该路径指向的文件否则在同步服务器的根目录packages/sync-server/即与package.json同级的目录查找config.json若不存在则在数据目录由ACTUAL_DATA_DIR决定见下文中查找config.json。当你从源码构建时配置文件应放在packages/sync-server/config.json当使用 Docker 时容器内的数据目录是/data因此config.json应放入挂载到/data的主机目录中。配置的生效优先级从低到高为内置默认值config.json中定义的键覆盖默认值环境变量覆盖config.json带_FILE后缀的从文件读取型环境变量优先级最高。有一个关键注意事项环境变量与config.json中的键并非一一对应。例如 JSON 中的嵌套对象upload.fileSizeSyncLimitMB对应扁平的ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB数组类型如allowedLoginMethods在环境变量中需要用逗号分隔的字符串表示。若对映射关系有疑问可直接核对源码中的 schema 定义packages/sync-server/src/load-config.js#L64。此外配置文件通过 convict 进行严格校验configSchema.validate({ allowed: strict })意味着 schema 中未定义的多余键会直接导致启动失败环境变量传入了非法值也会抛错例如loginMethod只能取password/header/openid三者之一。配置加载时还会通过debug模块输出诊断日志如果你怀疑配置没有被正确解释可以按 服务器故障排查文档 的说明开启 debug 日志定位问题。通过文件注入密钥Docker Secrets / Kubernetes仓库在常规环境变量之上额外支持_FILE后缀变量ACTUAL_OPENID_CLIENT_SECRET_FILE与ACTUAL_GITHUB_TOKEN_FILE分别指向存放 OpenID 客户端密钥和 GitHub Token 的文件路径。这与 Docker secrets、Kubernetes secret volume 的工作方式天然契合避免把密钥明文写进环境或配置文件。其实现位于 packages/sync-server/src/config-file-env.tsapplyFileEnv读取文件内容readFileSync后trim()并通过config.set(path, value)写入 convict 配置。源码注释明确了设计意图——_FILE变量在loadFile之后应用因此它同时压过config.json和普通环境变量且在校验之前生效load-config.js#L325-L334。读取失败会抛出形如Could not read ACTUAL_GITHUB_TOKEN_FILE from ...的错误。命令行工具CLI对自身涉及的密钥也支持同样的_FILE后缀详见 CLI 文档的环境变量一节。数据目录相关配置ACTUAL_DATA_DIRconfig.json 键dataDir服务器存储预算数据文件的根目录当未设置ACTUAL_CONFIG_PATH时配置文件的查找也依赖该目录。默认逻辑见 load-config.js#L18-L22若系统存在/data目录则使用/data否则使用同步服务器的项目根目录projectRoot即packages/sync-server/测试环境下默认使用projectRoot。dataDir本身是userFiles与serverFiles的默认基准目录。ACTUAL_CONFIG_PATH指定配置文件的具体路径。它无法在config.json内部设置——因为服务器正是用它来找到config.json的。未设置时服务器按前文所述顺序在项目根目录与数据目录中查找。serverFiles环境变量ACTUAL_SERVER_FILES服务器会在该目录中生成一个account.sqlite文件其中保存服务器密码哈希形式服务器已知的所有预算文件列表当前活跃的会话 token未来可能需要持久化的其他服务器级状态。默认值为dataDir下的server-files子目录即/data/server-files或与package.json同级的server-files。userFiles环境变量ACTUAL_USER_FILES服务器将所有预算文件以二进制 blob 形式存放在该目录。默认值为dataDir下的user-files子目录。源码 packages/sync-server/src/util/paths.ts 展示了实际命名规则每个预算文件对应一个file-fileId.blob协作分组文件对应group-groupId.sqlitefileId/groupId必须匹配^[a-zA-Z0-9_-]$的严格格式。对这两个目录请确保你的备份策略覆盖它们——预算数据与服务器状态都在其中。上传大小限制服务器通过三组配置限制上传体积schema 见 load-config.js#L172-L195在 app.ts 中被转换为 Express 的 body 解析上限config.json 键环境变量默认值作用upload.fileSizeSyncLimitMBACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB20普通同步文件application/actual-sync的最大体积MBupload.syncEncryptedFileSizeLimitMBACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB50加密同步文件application/encrypted-file的最大体积MBupload.fileSizeLimitMBACTUAL_UPLOAD_FILE_SIZE_LIMIT_MB20通用 JSON 上传体express.json的最大体积MB它们分别对应express.raw两种 MIME 类型与express.json的limit配置app.ts#L43-L57。如果你的预算文件较大例如历史数据庞大或包含大量附件可适当调高这些值。网络监听端口与主机名port环境变量ACTUAL_PORT服务器监听端口默认5006。源码中同时兼容process.env.PORTload-config.js#L87-L92并在run()中对字符串端口做了parseInt转换app.ts#L197-L199。hostname环境变量ACTUAL_HOSTNAME服务器绑定的主机名默认::——在大多数操作系统上这意味着同时监听 IPv4 与 IPv6。若只想监听本机回环地址可设为127.0.0.1配合反向代理暴露端口是常见的自托管拓扑。HTTPS 配置https是一个嵌套对象包含key私钥文件路径环境变量ACTUAL_HTTPS_KEYcert证书文件路径环境变量ACTUAL_HTTPS_CERT其他任意 Node.jstls.createServer()、tls.createSecureContext()或http.createServer()支持的选项可选大多数场景无需设置。一个最小示例{ https: { key: /data/selfhost.key, cert: /data/selfhost.crt } }服务端逻辑见 app.ts#L219-L233当https.key与https.cert同时非空时使用node:https创建 HTTPS 服务否则回退为普通 HTTP。值得注意的细节是parseHTTPSConfig如果传入的值以-----BEGIN开头会被当作 PEM 内容直接使用否则当作文件路径读取——这意味着ACTUAL_HTTPS_KEY/ACTUAL_HTTPS_CERT既可以填路径也可以直接填证书内容。如果你无法在环境变量中放入换行可以用\n转义服务器会自动还原为换行。如何获取证书并启用 HTTPS只有当你从公网访问服务器时才必须启用 HTTPS仅在 localhost 使用或由云厂商代管 HTTPS 时无需配置。完整的操作指引见 Activating HTTPS核心步骤为获取证书自签名证书可用mkcert自动生成或使用 OpenSSL 手动生成openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout selfhost.key -out selfhost.crt只需输入两位国家代码其余字段可留空回车。注意自签名证书会让浏览器显示安全警告且证书泄露将危及本机安全流量无需暴露公网即可获得有效证书使用 Tailscale HTTPS 或 Caddy 的 DNS challenge 等方式签发证书。写入配置按上文config.json示例填写密钥与证书路径Docker 容器中路径必须在容器内可见挂载卷对应/data或设置ACTUAL_HTTPS_KEY与ACTUAL_HTTPS_CERT环境变量。若使用自签名证书且用 Docker Compose 做健康检查需要在 health check 命令中加NODE_EXTRA_CA_CERTS/data/selfhost.crt环境变量test: [ CMD-SHELL, NODE_EXTRA_CA_CERTS/data/selfhost.crt node src/scripts/health-check.js, ]桌面端连接在服务器在哪里界面输入https://开头的服务器地址若提示选择证书选择对应证书重试使用 mkcert 时通过mkcert -CAROOT找到根 CA 目录并指定其中的rootCA.pem而不是服务器证书本身。验证用 HTTPS 访问服务器建议在新标签页重新输入 URL 测试而非在报错页面上刷新。前端静态资源webRoot环境变量ACTUAL_WEB_ROOT高级配置多数用户无需修改。默认情况下服务器会直接提供actual-app/web包中构建好的前端文件生产构建路径来自actual-app/web/package.json旁的build目录见 load-config.js#L26-L30。如果你想提供自定义前端需要将webRoot指向包含前端构建产物的目录在该目录顶层放置index.html它会被路由到/提供服务。生产模式下 Express 使用express.static(webRoot)提供静态文件并对所有未匹配路由回退到index.htmlapp.ts#L174-L177。开发模式下则反向代理到 Vite 开发服务器http://localhost:3001。登录方式loginMethod与allowedLoginMethodsloginMethod环境变量ACTUAL_LOGIN_METHOD默认认证方式合法值值说明password默认标准密码认证header通过 HTTP 头x-actual-password自动登录。高级用法配置不当会带来安全风险openidOpenID 认证预览特性allowedLoginMethods环境变量ACTUAL_ALLOWED_LOGIN_METHODS服务器允许接受的登录方式白名单默认[password, header, openid]。若想拒绝某些登录方式例如禁止 header 自动登录应修改此设置。作为环境变量传入时使用逗号分隔的字符串例如ACTUAL_ALLOWED_LOGIN_METHODSpassword,openid。schema 定义见 load-config.js#L123-L134。如果你计划部署多用户协作或 OpenID 登录可进一步阅读 OAuth/OpenID 认证配置 与 多用户管理后者要求先配置 OpenID Provider用户身份从 Provider 获取并区分 Basic/Admin 两种角色。反向代理信任trustedProxies与trustedAuthProxies当服务器运行在反向代理如 Nginx、Caddy、Traefik之后时Express 需要知道哪些代理是可信的才能从X-Forwarded-For等头中正确还原客户端真实 IP——这对限流等场景至关重要。trustedProxies环境变量ACTUAL_TRUSTED_PROXIES用于app.set(trust proxy, ...)app.ts#L31从客户端 IP 列表中剔除已知代理 IP。默认值为常见内网段10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7, ::1/128环境变量同样用逗号分隔传入。若你的代理位于公网地址如某些云负载均衡器需要把它的 IP 段追加进来。trustedAuthProxies环境变量ACTUAL_TRUSTED_AUTH_PROXIES单独配置允许通过 HTTP 头进行认证的客户端。默认继承trustedProxies的值但可独立覆盖。这在代理负责认证如 SSO 网关注入认证头仅信任该代理的认证头的场景下非常有用。注意源码中trustedAuthProxies的 schema 默认值为空数组[]load-config.js#L147-L152文档所述默认跟随 trustedProxies的行为由使用侧逻辑决定配置时建议显式设置。更多反向代理部署细节见 Using a Reverse Proxy。其他源码中可见的配置项除上述文档正式收录的键之外config.json与对应环境变量中还包含以下项目同样定义于 load-config.js 的 schemaconfig.json 路径环境变量默认值说明envNODE_ENVdevelopment运行环境production/development/test影响限流是否启用、前端资源代理方式mode—development/test应用模式通过/mode路由暴露文档标注当前未被前端实际调用token_expirationACTUAL_TOKEN_EXPIRATIONnever会话 token 过期策略支持never、openid-provider或非负秒数自定义校验格式见 load-config.test.jsenforceOpenIdACTUAL_OPENID_ENFORCEfalse是否强制 OpenID 认证openId.*ACTUAL_OPENID_*空OpenID 发现的各项端点discovery URL、authorization/token/userinfo 端点、client_id、client_secret、server_hostname、authMethod 等userCreationModeACTUAL_USER_CREATION_MODEmanual用户创建方式manual/logingithub.tokenACTUAL_GITHUB_TOKEN空GitHub API 个人访问令牌供文档/发布相关功能使用可用ACTUAL_GITHUB_TOKEN_FILE从文件注入corsProxy.enabledACTUAL_CORS_PROXY_ENABLEDfalse是否为前端插件启用 CORS 代理端点启用后挂载/cors-proxy路由见 app.ts#L68-L70一个聚合以上内容的完整示例config.json{ dataDir: /data, serverFiles: /data/server-files, userFiles: /data/user-files, port: 5006, hostname: ::, https: { key: /data/selfhost.key, cert: /data/selfhost.crt }, loginMethod: password, allowedLoginMethods: [password, openid], trustedProxies: [ 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7, ::1/128 ], upload: { fileSizeSyncLimitMB: 20, syncEncryptedFileSizeLimitMB: 50, fileSizeLimitMB: 20 } }小结Actual 同步服务器的配置体系可以概括为三个要点默认值 → config.json → 环境变量 →_FILE环境变量的优先级链JSON 嵌套键与扁平环境变量的非对称映射以 load-config.js 的 convict schema 为唯一事实来源以及严格校验——任何未知键或非法取值都会在启动阶段直接暴露。掌握这些规则后无论是 Docker 部署、反向代理接入还是 HTTPS 启用都能通过统一的配置心智模型快速定位问题配合 debug 日志即可高效排查。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考