MyFin Budget 配置参数详解

目标：把 MyFin Budget 的全部配置项讲透——三个服务各自吃什么配置、每一项的默认值与取值效果、哪些是必配哪些可选、生产环境怎么配。参数语义以官方 .env.example 与 myfin-api 5.5.0 源码为准，关键行为（迁移、限流、会话、注入）均在 Ubuntu 22.04 实测环境验证并附真实回显。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS x86_64
• 软件版本：myfin-api 5.5.0（Node.js + Express + Prisma）、myfin 前端 10.7.0、MySQL 8.4（实测落盘 8.4.13）
• 配置来源：官方 .env.example（https://raw.githubusercontent.com/afaneca/myfin-api/master/.env.example，2026-10-24 版）、官方 docker-compose.yml、源码实查（app.ts / rateLimiter.ts / sessionManager.ts / consts.js）
• 实测环境部署形态：官方三服务编排（部署过程见《MyFin Budget Docker Compose 部署指南》），API 映射宿主 8151、前端 8150
• 参数体系：纯环境变量驱动，两个应用镜像均无挂载式配置文件

二、前置条件

1. 已按部署指南完成三服务部署并能登录（本文所有「验证」动作均基于运行中的实例）。
2. 修改配置的方式统一为「改 compose 环境变量 → 重建对应服务」：

cd /opt/myfin
vim docker-compose.yml   # 修改 environment 段
docker compose up -d     # 只重建配置变化的服务

实测回显（改动 myfin-api 后重建，其余服务不受影响）：

Container myfin-db  Running
Container myfin-api Recreate
Container myfin-api Recreated
Container myfin-db  Waiting
Container myfin-db  Healthy
Container myfin-api Starting
Container myfin-api Started

3. 查看当前生效配置的方法：容器环境变量即最终事实：

docker exec myfin-api env | grep -E '^(DB_|PORT|LOGGING|BYPASS|ENABLE|TRUST_PROXY)'

实测回显：

PORT=3001
LOGGING=false
DB_NAME=myfin
DB_USER=myfin
DB_PW=myfinpassword
DB_PORT=3306
DB_HOST=db
BYPASS_SESSION_CHECK=false
ENABLE_USER_SIGNUP=false
TRUST_PROXY=1

三、参数查看与修改方式

3.1 三层配置入口

3.2 启动日志与迁移机制

API 容器每次启动都会执行 Prisma 迁移，这也是「配置改坏了先看启动日志」的入口（docker logs myfin-api 实测回显）：

Datasource "db": MySQL database "myfin" at "db:3306"

21 migrations found in prisma/migrations


No pending migrations to apply.
🌐 i18next is maintained with support from Locize — consider powering your project with managed localization (AI, CDN, integrations): https://locize.com 💙
MyFin server listening on port 3001

逐行解读：Datasource 行显示最终拼出的数据库连接目标（DB_HOST:DB_PORT/DB_NAME 是否传对，看这一行最直接）；21 migrations found 是 5.5.0 内置迁移脚本总数；No pending migrations to apply. 表示库结构已同步；最后一行表示 API 在 PORT 指定端口监听成功。若数据库四要素（DB_HOST/DB_PORT/DB_NAME/DB_USER/DB_PW）配错，日志会停在 Prisma 连接报错处，MyFin server listening 不会出现——这是判断配置生效最快的分界线。

四、参数总览

myfin-api 全量环境变量（来源：官方 .env.example 与 docker-compose.yml，分组列出）：

💡 说明：.env.example 与官方 compose 的默认值有四处不一致（DB_PORT 3406/3306、ENABLE_USER_SIGNUP true/false、TRUST_PROXY false/1、SMTP_FROM 带值/空）。容器化部署一律以官方 docker-compose.yml 为准——.env.example 服务于「源码直跑」形态（本地开发时 npm start 读 .env）。

五、核心参数分类详解

5.1 数据库连接组（DB_*）

五件套决定 API 与 MySQL 的连接。实测要点：

• DB_HOST 用服务名：compose 网络内 db 即主机名（内置 DNS 解析），不要写容器 IP（重建即变）。官方 compose 原文即 DB_HOST=db。
• DB_PORT 是「数据库侧」端口：MySQL 容器内监听 3306，无论宿主映射到哪个端口，这里永远写 3306——除非你自定义了 MySQL 容器内端口。
• 改口令要两头同步：MYSQL_PASSWORD（db 侧）与 DB_PW（api 侧）必须一致；MySQL 已初始化后再改 MYSQL_PASSWORD 环境变量不会自动改库内口令（MySQL 镜像只在首次初始化空数据目录时应用该变量），需要 docker exec -it myfin-db mysql -uroot -p -e "ALTER USER 'myfin'@'%' IDENTIFIED BY '新口令';" 手工同步。
• 连接失败的分界现象：任一要素错误，启动日志停在 Prisma 报错（见 3.2），Web 端表现为登录接口 5xx。

💡 技术拓展：MyFin 通过 Prisma ORM 访问 MySQL，还接受标准连接串 DATABASE_URL="mysql://myfin:myfinpassword@localhost:3406/myfin"（官方 .env.example 原样给出）。四要素+端口与连接串二选一即可，容器化 compose 形态统一用四要素写法，不传 DATABASE_URL。

5.2 注册与会话控制组

• ENABLE_USER_SIGNUP（默认 false，官方 compose）：控制「除第一个用户外」是否允许自助注册。源码逻辑（userController.ts 实查）：注册接口在 process.env.ENABLE_USER_SIGNUP !== 'true' 时直接拒绝。个人自用保持 false 最安全。
• 第一个用户的特殊性：首个用户只能通过 POST /setup/init 创建，且全系统没有任何用户时才允许（源码 setupService.ts 实查 if (userCount != 0) throw APIError.notAcceptable();）。实测已有用户后重复调用返回 HTTP 406：

curl -s -o /dev/null -w "%{http_code}" -X POST http://localhost:8151/setup/init \
  -H 'Content-Type: application/json' \
  -d '{"username":"x","password":"y1234567","email":"x@example.com","currency":"USD"}'

实测回显：

406

• 会话有效期（内置常量，非环境变量）：Web 端 30 分钟滑动续期、移动端 30 天（源码 sessionManager.ts 实查 30 * 60 秒 / 30 * 24 * 60 * 60 秒）。每次携带有效 sessionkey 的请求都会把有效期顺延一个窗口（trustlimit 机制），长期不用才过期，过期后重新登录即可。此值编译在镜像内，如需调整只能改源码重构建。

5.3 安全与代理组（TRUST_PROXY）

TRUST_PROXY 是安全敏感度最高的参数，映射到 Express 的 trust proxy 设置，语义由官方 .env.example 注释完整定义（原文翻译）：

它直接影响限流的 IP 识别：API 全局限流为每分钟每 IP 100 请求（源码 rateLimiter.ts 实查 windowMs: 60 * 1000, limit: 100，超限回显 You have exceeded your 100 requests per minute limit.）。无反代却设 TRUST_PROXY=1 时，客户端可伪造 X-Forwarded-For 绕过限流——所以部署指南提醒「直连时删除该变量」。

5.4 日志与调试组

• LOGGING（默认 false）：开启后 API 输出请求级详细日志。源码中 Logger.addLog 受其控制；排障时可临时置 true 重建后 docker compose logs -f myfin-api 观察。启动日志（Prisma 连接目标、迁移、监听端口）不受此开关影响，始终输出。
• BYPASS_SESSION_CHECK（默认 false）：置 true 后所有业务接口跳过会话校验（源码 commonsController.ts 实查 bypassSessionChecking = process.env.BYPASS_SESSION_CHECK === 'true'）。仅限本机调试，生产环境严禁开启——等于关掉全部鉴权。
• NODE_ENV：官方 .env 示例为 production。源码实查：仅当 NODE_ENV == "development" 时挂载 Swagger 文档界面（registerSwagger），生产保持 production 即无 Swagger 暴露。

5.5 邮件组（SMTP_*）

六个变量控制密码找回邮件（OTP 流程：POST /auth/recovery/sendOtp 发码 → POST /auth/recovery/setNewPassword 设新密）。全部留空（compose 默认）时找回流程不可用，仅能靠管理员在数据库侧重置。启用示例（compose environment 写法）：

      - SMTP_HOST=smtp.example.com
      - SMTP_PORT=465
      - SMTP_SECURE=true
      - SMTP_USER=no-reply@example.com
      - SMTP_PASSWORD=${SMTP_PASSWORD}
      - SMTP_FROM=no-reply@example.com

⚠️ 注意：SMTP_PASSWORD 属敏感值，用环境变量注入（export SMTP_PASSWORD=... 后经 compose 变量替换传入），不要明文写进 compose 文件提交到仓库。

5.6 前端组（VITE_MYFIN_BASE_API_URL）

前端镜像唯一的必配变量。语义与生效机制（部署指南已实测）：该值在容器启动时注入前端 JS 产物，浏览器随后直接向该地址发起 API 请求。三种典型取值：

取值原则：浏览器能直接访问到（含端口、协议），且与实际访问方式一致；跨协议（https 页面调 http API）会被浏览器混合内容策略拦截。

5.7 记账本位币与货币清单

实例初始化（POST /setup/init）时选定本位币，可选项来自后端内置货币表（源码 consts.js 实查，共 20 余种）：EUR、USD、CHF、BRL、GBP、CAD、MXN、JPY、AUD、INR、DKK、SEK、NOK、PLN、ISK、CZK、HUF、RON、CNY（人民币）、SGD、MYR 等。后续可用 PUT /users/changeCurrency 变更（实测 {"currency":"EUR"} 成功回显 "Currency was successfully updated"）——注意这只是显示/记账本位币切换，不做汇率换算。

5.8 MySQL 服务端参数（可选挂载）

MySQL 侧可调参数经 my.cnf 挂载 /etc/mysql/conf.d/ 生效（字符集、连接数示例见部署指南第七节）。与 MyFin 强相关的两个观察：

• 账本数据由 Prisma 迁移管理，默认 utf8mb4，无需额外字符集配置；
• 金额以整数分值存储（实测 GET /user/backup 返回 current_balance: 315750 对应 3157.50），不存在浮点精度配置问题。

六、生产配置模板

适用于「个人/家庭自用、1 核 2GB 起步的小型服务器、Nginx 反代 + HTTPS」的推荐配置（要点以注释标注）：

services:
  myfin-api:
    image: ghcr.io/afaneca/myfin-api:5.5.0    # 锁定版本，不用 latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8151:3001"                 # 只绑回环，外网经反代访问
    environment:
      - DB_NAME=myfin
      - DB_USER=myfin
      - DB_PW=${DB_PW}                        # 敏感值经环境变量注入
      - DB_PORT=3306
      - DB_HOST=db
      - PORT=3001
      - LOGGING=false                         # 生产关闭详细日志
      - BYPASS_SESSION_CHECK=false            # 永远保持 false
      - ENABLE_USER_SIGNUP=false              # 个人实例关闭注册
      - TRUST_PROXY=1                         # 有 Nginx 反代时信任第 1 跳
      - SMTP_HOST=smtp.example.com            # 配齐邮件找回
      - SMTP_PORT=465
      - SMTP_SECURE=true
      - SMTP_USER=no-reply@example.com
      - SMTP_PASSWORD=${SMTP_PASSWORD}
      - SMTP_FROM=no-reply@example.com
    depends_on:
      db:
        condition: service_healthy

  myfin-frontend:
    image: ghcr.io/afaneca/myfin:10.7.0
    restart: unless-stopped
    ports:
      - "127.0.0.1:8150:80"
    environment:
      - VITE_MYFIN_BASE_API_URL=https://myfin.example.com/api  # 反代后的对外 API 地址
    depends_on:
      myfin-api:
        condition: service_healthy

模板解读：

• 镜像锁版本（5.5.0/10.7.0）：升级改为新 tag 重建，出问题秒回滚；
• 端口绑 127.0.0.1：外网流量全部走 Nginx/Traefik 终结 TLS，API 与前端不直接暴露公网；
• TRUST_PROXY=1：与「一层反代」匹配，限流统计的是真实客户端 IP；
• 敏感值 ${DB_PW}/${SMTP_PASSWORD}：写入 .env（与 compose 同目录，权限 600）或由部署系统注入；
• 适用资源：1 核 2GB 内存 + 20GB 磁盘可稳定运行（MySQL 8.4 + Node.js 单进程 + nginx 静态托管为轻负载组合）；个人账本数据量（万级交易）对资源无压力。

七、常见问题

Q1：改了 compose 里的配置但不生效？ 确认是否执行了 docker compose up -d（只 restart 不重读环境变量），并用 docker exec myfin-api env | grep DB_ 核对容器内实际值（见 2.2）。

Q2：改了 MYSQL_PASSWORD 后 API 连不上库？ MySQL 镜像只在首次初始化时应用口令变量，之后改变量不改库内口令。用 5.1 的 ALTER USER 同步，或清空数据卷重新初始化（会丢数据，先备份）。

Q3：TRUST_PROXY 该填什么？ 数反代层数：无反代 false/删除；一层 Nginx 用 1；Cloudflare+Nginx 用 2。拿不准时用 false（限流按连接 IP 统计，安全侧倾斜）。

Q4：Swagger 文档打不开？ Swagger 仅在 NODE_ENV=development 时启用（源码实查），生产配置本就不暴露。如需本地查看 API 文档，临时用 development 模式跑一个仅绑定 127.0.0.1 的调试实例，或直接看 API 使用详解篇的端点清单。

Q5：启用注册开关后谁能注册？ ENABLE_USER_SIGNUP=true 后任何人都能调 POST /users 自助建号（各用户账本隔离）。公网实例不建议开启；确需多人使用时，先在私网注册完再关回 false。

Q6：限流触发怎么办？ 单 IP 每分钟 100 请求（内置常量）。正常人工操作不会触顶；脚本批量调用时把请求节奏控制在 100/分钟以内，触发后等窗口重置即可，无需重启服务。

八、参考链接

• 官方 .env.example：https://raw.githubusercontent.com/afaneca/myfin-api/master/.env.example
• 官方 docker-compose.yml：https://github.com/afaneca/myfin/blob/master/docker-compose.yml
• myfin-api 源码（app.ts / rateLimiter.ts / sessionManager.ts / consts.js）：https://github.com/afaneca/myfin-api
• 站内延伸：《MyFin Budget 介绍与选型指南》、《MyFin Budget Docker Compose 部署指南》、《MyFin Budget API 使用详解》