IHateMoney 7.2.1 配置参数详解

目标：逐参数讲清 IHateMoney 7.2.1 的全部配置项——参数含义、默认值、修改方式与生效验证，重点参数附「修改 → 重启 → 观察行为变化」的实测证据与踩坑实录（管理口令哈希算法、API 创建收口、子路径部署等）。已在 Ubuntu 22.04 + ihatemoney 7.2.1（pip 安装 + Gunicorn/systemd 形态，安装过程见《Ubuntu 22.04 安装 IHateMoney 7.2.1 指南》）、Docker 镜像 ihatemoney/ihatemoney:7.2.1（环境变量形态）实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• IHateMoney：7.2.1（pip 安装，虚拟环境 /home/ihatemoney/ihatemoney）
• 运行形态：Gunicorn 26.2.0（3 workers，监听 127.0.0.1:8000）+ systemd（ihatemoney.service）+ Nginx 反代
• 配置文件：/etc/ihatemoney/ihatemoney.cfg（属主 root:ihatemoney，权限 740）
• 数据库：SQLite /var/lib/ihatemoney/ihatemoney.sqlite
• 对照形态：Docker 官方镜像 ihatemoney/ihatemoney:7.2.1（环境变量注入配置，详见《IHateMoney 7.2.1 Docker Compose 部署指南》）
• 管理口令约定：演示管理口令 q1w2e3r4，文中哈希均为该口令生成

二、前置条件

本篇的实测均基于一篇已安装好的可运行实例，开始前确认服务健康：

systemctl is-active ihatemoney.service
curl -s -o /dev/null -w "home HTTP %{http_code}\n" http://127.0.0.1:8000/

实测回显：

active
home HTTP 200

同时确认已有一批测试项目（后文参数实测会用到 limited 项目与其私有码 q1w2e3r4）：

curl -s --basic -u limited:q1w2e3r4 http://127.0.0.1:8000/api/projects/limited | head -c 160

实测回显：

{"id": "limited", "name": "limited", "contact_email": "admin@example.com", "logging_preference": 1, "members": [], "default_currency": "XXX"}

三、参数查看与修改方式

3.1 参数从哪里读

• 原生/pip 形态：默认读 /etc/ihatemoney/ihatemoney.cfg；可用环境变量 IHATEMONEY_SETTINGS_FILE_PATH 指向其他文件（必须绝对路径，相对路径会被解释到 /etc/ihatemoney/ 下）。
• 官方镜像形态：entrypoint 每次启动用环境变量重写 /etc/ihatemoney/ihatemoney.cfg，配置以环境变量为准，同名挂载会被覆盖。
• 优先级：配置文件（或镜像环境变量生成的文件）> 代码内默认值（default_settings.py）。

3.2 改参数的标准动作（改 → 重启 → 验证）

配置文件是 Python 语法（键 = 值），每次修改后必须重启服务才生效：

vi /etc/ihatemoney/ihatemoney.cfg     # 修改参数
systemctl restart ihatemoney.service  # 重启生效
systemctl is-active ihatemoney.service

实测回显：

active

💡 说明：镜像形态等价动作是改 compose 的 environment: 后 docker compose up -d；本文所有实测以原生形态为主，镜像形态差异在对应参数处标注。

3.3 生成配置模板

全新安装时模板由官方 CLI 生成（自带随机 SECRET_KEY 与合理默认值）：

runuser -u ihatemoney -- bash -c 'source /home/ihatemoney/ihatemoney/bin/activate && ihatemoney generate-config ihatemoney.cfg' > /etc/ihatemoney/ihatemoney.cfg

模板共 60 行（7.2.1 实测），包含下文除 SITE_NAME、PASSWORD_HASH_* 之外的全部参数。

四、参数总览

7.2.1 全部配置参数清单（默认值取自 7.2.1 生成模板与镜像内置默认 Env，两形态默认不同处已标注；「实测」列说明本文验证方式）：

💡 技术拓展：SQLALCHEMY_DATABASE_URI 一参背后是 SQLAlchemy 的数据库方言体系——sqlite:////绝对路径（SQLite）、postgresql://用户:口令@主机/库（psycopg2）、mysql+pymysql://用户:口令@主机/库（PyMySQL）三类常用前缀对应三种后端。常见选项对比：

后端	URI 前缀	依赖驱动	适用场景
SQLite	sqlite:////路径	内置	单机/家庭/小团队，零运维
PostgreSQL	postgresql://…	psycopg2（镜像已内置）	多实例/专业备份/高并发
MariaDB ≥10.3.2	mysql+pymysql://…	PyMySQL（镜像已内置）	已有 MySQL 系设施

本文实测环境采用 SQLite（官方文档明示「中小规模够用」），理由是零依赖且备份=拷贝单文件。

五、核心参数分类详解

5.1 数据库与调试类

SQLALCHEMY_DATABASE_URI——最关键的参数，决定数据落在哪。SQLite 为「四斜杠 + 绝对路径」格式（前两个斜杠是 URI 分隔，后两个是路径根）：

grep "^SQLALCHEMY_DATABASE_URI" /etc/ihatemoney/ihatemoney.cfg
ls -lh /var/lib/ihatemoney/ihatemoney.sqlite

实测回显：

SQLALCHEMY_DATABASE_URI = 'sqlite:////var/lib/ihatemoney/ihatemoney.sqlite'
-rw-r--r-- 1 ihatemoney ihatemoney 144K Oct 23 11:26 ihatemoney.sqlite

切 PostgreSQL/MariaDB 的写法见第四章总览与《IHateMoney 7.2.1 Docker Compose 部署指南》4.2 节（镜像形态 PG 栈实测）。验证要点：改 URI 后执行 ihatemoney db upgrade head，新库文件出现且迁移完成即为生效。

DEBUG——调试总开关，生产必须 False。模板中还有一行 SQLACHEMY_ECHO = DEBUG，这是一个历史遗留的拼写键（正确拼写应为 SQLALCHEMY_ECHO）：

grep -rn "SQLACHEMY_ECHO" /home/ihatemoney/ihatemoney/lib/python3.11/site-packages/ihatemoney/default_settings.py

实测回显：

/home/ihatemoney/ihatemoney/lib/python3.11/site-packages/ihatemoney/default_settings.py:2:DEBUG = SQLACHEMY_ECHO = False

代码仅在默认设置里对该键赋值，无任何消费点——该键当前无实际效果（排查配置时不必纠结它）。要临时看 SQL 语句，直接把 DEBUG 设为 True 重启即可。

SQLALCHEMY_TRACK_MODIFICATIONS——Flask-SQLAlchemy 事件通知开关，7.2.1 模板默认 False，保持默认即可（True 只会增加内存开销，并无功能收益）。

5.2 安全与会话类

SECRET_KEY——会话 Cookie 与 API Token 的签名密钥，是全站安全的核心。官方明确警告：密钥可预测时攻击者可绕过私有码校验登录任意项目。不配置或用弱值时，应用启动直接打印警告：

UserWarning: Running a server without changing the SECRET_KEY can lead to user impersonation. Please update your configuration file.

（实测回显，出自服务日志。）镜像形态默认值是公开演示串 tralala，用镜像部署必须显式覆盖。生成强密钥：

python3 -c 'import secrets; print(secrets.token_hex(32))'

实测回显：

6d625d1d54514763dee0c94bf2655ae8dce023a20eebd32b6f02159d8484de24

ADMIN_PASSWORD——管理操作（管理仪表盘、Web 收口建项目）的口令，只能存哈希。这是 7.x 实测中坑最多的参数，三个坑依次呈现：

坑一：7.2.1 的启动校验只认 pbkdf2: 前缀的哈希。用 werkzeug 3.x 默认生成的 scrypt: 前缀哈希（哈希本身有效）会被判定为「未哈希」并拒绝用于管理端点，日志每次启动都会警告：

UserWarning: The way Ihatemoney stores your ADMIN_PASSWORD has changed. You are using an unhashed ADMIN_PASSWORD, which is not supported anymore and won't let you access your admin endpoints. Please use the command 'ihatemoney generate_password_hash' to generate a proper password HASH and copy the output to the value of ADMIN_PASSWORD in your settings file.

（实测回显，出自服务日志；判定代码位于 run.py 第 115 行：if "pbkdf2:" not in app.config["ADMIN_PASSWORD"] and app.config["ADMIN_PASSWORD"]:。）

坑二：按官方说明配 PASSWORD_HASH_METHOD = "pbkdf2:600000" 生成哈希时，OpenSSL 3 环境直接报错（默认摘要 SHA-1 被拒）：

_hashlib.UnsupportedDigestmodError: [digital envelope routines] unsupported

（实测回显。）解决：显式指定 SHA-256。

坑三：方法串格式是 pbkdf2:摘要:轮数（摘要在前），写成 pbkdf2:600000:sha256 会报 ValueError: invalid literal for int() with base 10: 'sha256'（实测回显）。

正确的完整配置与生成流程：

# 1. 配置哈希方法（显式 sha256，规避 OpenSSL 3 的 SHA-1 限制）
echo 'PASSWORD_HASH_METHOD = "pbkdf2:sha256:600000"' >> /etc/ihatemoney/ihatemoney.cfg
# 2. 重新生成哈希（交互输入 q1w2e3r4）
echo q1w2e3r4 | runuser -u ihatemoney -- bash -c 'source /home/ihatemoney/ihatemoney/bin/activate && ihatemoney generate_password_hash'

实测回显：

Password:
pbkdf2:sha256:600000$McPyRJB2rTM4JmpK$4932dea62d142bd0b8b3294edcefeacd83e308ed6b4466410b48f0ac9b7eaf6b

（哈希格式：pbkdf2:摘要:轮数$盐$摘要值，盐段 McPyRJB2rTM4JmpK 共 16 字符，与默认盐长一致。）配置 ADMIN_PASSWORD = 'pbkdf2:sha256:600000$McPyRJB2rTM4JmpK$4932dea62d142bd0b8b3294edcefeacd83e308ed6b4466410b48f0ac9b7eaf6b'（演示口令 q1w2e3r4 生成）并重启后，警告消失（journalctl 中不再出现 unhashed 警告），管理端点恢复可用。生效验证（Web 表单带 CSRF 会话实测）：

rm -f /tmp/jar
CSRF=$(curl -s -c /tmp/jar http://127.0.0.1:8000/admin | grep -oE 'value="[A-Za-z0-9_.-]{40,}' | cut -d'"' -f2 | head -1)
curl -s -b /tmp/jar -o /dev/null -w "POST 正确口令 HTTP %{http_code} redirect=%{redirect_url}\n" -X POST http://127.0.0.1:8000/admin -d "admin_password=q1w2e3r4&csrf_token=$CSRF"
curl -s -b /tmp/jar -o /dev/null -w "POST 错误口令 HTTP %{http_code}\n" -X POST http://127.0.0.1:8000/admin -d "admin_password=wrongpass&csrf_token=$CSRF"

实测回显：

POST 正确口令 HTTP 302 redirect=http://127.0.0.1:8000/
POST 错误口令 HTTP 200

⚠️ 注意：ADMIN_PASSWORD = ""（空串）时管理功能整体禁用（/admin 无法登录、Web 收口建项目不可用），这是官方设定的默认安全态。

PASSWORD_HASH_METHOD——口令哈希算法，默认 None（取 werkzeug 当前默认，即 scrypt）。如上所述，生产建议固定为 "pbkdf2:sha256:600000" 以兼容 7.2.1 的校验逻辑。

PASSWORD_HASH_SALT_LENGTH——哈希盐长度，默认 None（实际 16 字符）。实测设 64 后 generate_password_hash 输出的盐段从 16 字符变为 64 字符（pbkdf2:sha256:600000$ 后第一段 wc -c 计数由 17 含换行变为 65 含换行）。保持默认即可，仅在高强度合规要求时调大。

SESSION_COOKIE_SECURE——会话 Cookie 是否带 Secure 标记。默认 True，但纯 HTTP 部署下浏览器拒绝回传该 Cookie，表现为「登录后一刷新又回登录页」（B1/B2 两篇实测中均按 False 处理）。HTTPS 部署必须回到 True。

ENABLE_CAPTCHA——建项目表单验证码。设 True 重启后，首页创建表单出现验证码输入框：

grep -E "^ENABLE_CAPTCHA" /etc/ihatemoney/ihatemoney.cfg   # ENABLE_CAPTCHA = True 时
curl -s http://127.0.0.1:8000/ | grep -oE 'name="captcha[^>]*' | head -1

实测回显：

name="captcha" placeholder="" type="text" value=""

⚠️ 注意：验证码开启期间，REST API 建项目同样会被拦截（表单校验含验证码字段），表现为 POST /api/projects 返回 400——公网实例开验证码后，API 建项目需临时关闭或改走 Web 流程（实测发现，官方文档未明示）。

5.3 项目创建与管理面类

ACTIVATE_DEMO_PROJECT——首页是否挂公共演示项目。实测开关效果（改 True 重启后首页 grep 计数 2，含演示项目入口；False 后为 0）：

curl -s http://127.0.0.1:8000/ | grep -ci "demo"

实测回显（ACTIVATE_DEMO_PROJECT=True 时）：

2

私有实例建议 False（本文生产定稿配置即 False）。

ACTIVATE_ADMIN_DASHBOARD——管理仪表盘开关，True 时 /admin 出现登录页，配合 ADMIN_PASSWORD 使用（登录实测见 5.2）。两者关系：仪表盘登录检查的是 ADMIN_PASSWORD 非空且哈希可校验；只开仪表盘不配口令等于没开。

ALLOW_PUBLIC_PROJECT_CREATION——是否允许匿名创建项目。这是 7.2.1 行为最出人意料的参数：设 False 后不仅 Web 表单要管理口令，REST API 的建项目与改项目也会被整体拦停（API 无管理口令旁路）。实测证据（False 状态下三连测）：

curl -s -o /dev/null -w "API建项目(无口令) HTTP %{http_code}\n" -X POST http://127.0.0.1:8000/api/projects -d "name=limited2&id=limited2&password=q1w2e3r4&contact_email=a@example.com"
curl -s -o /dev/null -w "API建项目(错口令) HTTP %{http_code}\n" -X POST http://127.0.0.1:8000/api/projects -d "name=limited2&id=limited2&password=q1w2e3r4&contact_email=a@example.com&admin_password=wrong"
curl -s -o /dev/null -w "API建项目(对口令) HTTP %{http_code}\n" -X POST http://127.0.0.1:8000/api/projects -d "name=limited2&id=limited2&password=q1w2e3r4&contact_email=a@example.com&admin_password=q1w2e3r4"
curl -s -o /dev/null -w "API改项目 HTTP %{http_code}\n" --basic -u limited:q1w2e3r4 -X PUT http://127.0.0.1:8000/api/projects/limited -d "name=limited&id=limited&current_password=q1w2e3r4&contact_email=admin@example.com"

实测回显（全部被拦）：

API建项目(无口令) HTTP 400
API建项目(错口令) HTTP 400
API建项目(对口令) HTTP 400
API改项目 HTTP 400

恢复 True 后，同样的 API 改项目请求立即成功：

"UPDATED"

HTTP 200

（API 层代码 api/common.py 的逻辑为：if form.validate() and current_app.config.get("ALLOW_PUBLIC_PROJECT_CREATION") —— 参数一关，创建/更新分支整体短路，与口令无关。）

选型建议：要用 REST API 自动化（脚本建项目/批量维护）的实例保持 True（用 Nginx 层做来源限制更合适）；纯人工 Web 使用、想收口创建权限的实例设 False。

5.4 站点呈现类

SITE_NAME——站点名称，改后浏览器标题与页面品牌即时变化（该参数不在生成模板里，需手工添加）。实测值 实验室记账站：

curl -s http://127.0.0.1:8000/ | grep -oE "<title>[^<]+" | head -1

实测回显（设置前/后对比）：

设置前：<title>I Hate Money — Account manager
设置后：<title>实验室记账站 — Account manager

APPLICATION_ROOT——子路径部署。设为 /ihm 重启后应用整体挂到 /ihm/ 下：

curl -s -o /dev/null -w "/ihm/ HTTP %{http_code}\n" http://127.0.0.1:8000/ihm/
curl -s -o /dev/null -w "/ihm/static/css/main.css HTTP %{http_code}\n" http://127.0.0.1:8000/ihm/static/css/main.css

实测回显：

/ihm/ HTTP 200
/ihm/static/css/main.css HTTP 200

适用场景：与站点其他应用共享域名时（如 https://example.com/ihm/）。注意 Nginx 反代需同步按子路径转发。

BABEL_DEFAULT_TIMEZONE——界面显示时区（内部时间一律 UTC 存储），未设置时随服务器系统时区。推荐显式声明 BABEL_DEFAULT_TIMEZONE = "Asia/Shanghai"，避免服务器迁移后账单日期显示漂移。镜像形态默认值为 UTC，与原生默认不同，跨国团队部署时注意核对。

LEGAL_LINK——页脚法律/隐私页链接（GDPR 合规用）。实测设为 https://example.com/privacy 后首页出现该链接：

curl -s http://127.0.0.1:8000/ | grep -oE "example.com/privacy" | head -1

实测回显：

example.com/privacy

SHOW_ADMIN_EMAIL——错误页（404/500）是否展示管理员邮箱，且仅当 MAIL_DEFAULT_SENDER 非默认值时才真正展示。隐私敏感的公网实例可设 False。

5.5 邮件类（MAIL_*）

邮件参数控制邀请成员、找回私有码两类邮件的发送，底层为 Flask-Mail。7.2.1 默认值（模板与镜像一致）：

💡 技术拓展：MAIL_USE_TLS 与 MAIL_USE_SSL 是两种不同的加密握手方式，不能同时为 True——

方式	握手	常用端口	参数组合
SSL/TLS 直连	先加密后对话	465	MAIL_USE_SSL=True
STARTTLS	明文起步、升级加密	587	MAIL_USE_TLS=True

本文实测环境未接入外部 SMTP（无真实邮件发送验证），上表为 7.2.1 代码默认值核验结果；实际接入外部邮箱时按服务商文档选择端口与对应开关即可。

六、生产配置模板

以下为本文实测定稿的完整配置文件（适用场景：家庭/小团队自托管，2 核 4GB 内存、普通 SSD、单机 SQLite、Nginx 反代、HTTP 内网或 HTTPS 外网均可——HTTPS 部署时把 SESSION_COOKIE_SECURE 改回 True）：

# ==== IHateMoney 生产配置（Ubuntu 22.04 实测定稿）====
DEBUG = False
SQLALCHEMY_DATABASE_URI = 'sqlite:////var/lib/ihatemoney/ihatemoney.sqlite'
SQLALCHEMY_TRACK_MODIFICATIONS = False
SECRET_KEY = "c81ad21cbe1c4b17aa97e42e33a1f8a05a5dfb28b660f4d18f4f2ba88a15d3e7"
MAIL_DEFAULT_SENDER = "Budget manager <admin@example.com>"
SHOW_ADMIN_EMAIL = True
ACTIVATE_DEMO_PROJECT = False
ADMIN_PASSWORD = 'pbkdf2:sha256:600000$McPyRJB2rTM4JmpK$4932dea62d142bd0b8b3294edcefeacd83e308ed6b4466410b48f0ac9b7eaf6b'  # 演示口令 q1w2e3r4 生成，生产环境须按 5.2 流程重新生成
ALLOW_PUBLIC_PROJECT_CREATION = True
ACTIVATE_ADMIN_DASHBOARD = True
BABEL_DEFAULT_TIMEZONE = "Asia/Shanghai"
SESSION_COOKIE_SECURE = False
APPLICATION_ROOT = "/"
ENABLE_CAPTCHA = False
SITE_NAME = "实验室记账站"
LEGAL_LINK = "https://example.com/privacy"
PASSWORD_HASH_METHOD = "pbkdf2:sha256:600000"

逐项要点：SECRET_KEY 每台机器独立生成勿复用；ADMIN_PASSWORD 用 5.2 的流程生成（scrypt 前缀无效，必须 pbkdf2 系）；ALLOW_PUBLIC_PROJECT_CREATION 若无需 API 自动化可改 False 收口（代价见 5.3）；SECRET_KEY/ADMIN_PASSWORD 属敏感值，配置文件权限收敛为 740、属组 ihatemoney。

定稿后全链路复验（本文实测）：

systemctl is-active ihatemoney.service
curl -s http://127.0.0.1:8000/ | grep -oE "<title>[^<]+" | head -1

实测回显：

active
<title>实验室记账站 — Account manager

七、常见问题（FAQ）

Q1：启动日志反复出现 "You are using an unhashed ADMIN_PASSWORD"，管理端点全部不可用？ 原因：7.2.1 只认 pbkdf2: 前缀哈希，werkzeug 3.x 默认生成的 scrypt: 前缀哈希被判为未哈希（实测证据见 5.2）。解决：配置 PASSWORD_HASH_METHOD = "pbkdf2:sha256:600000" 后重新生成哈希替换。

Q2：ihatemoney generate_password_hash 报 _hashlib.UnsupportedDigestmodError: [digital envelope routines] unsupported？ 原因：方法串 pbkdf2:600000（不带摘要）默认走 SHA-1，被 OpenSSL 3 拒绝。解决：写成 pbkdf2:sha256:600000（注意摘要在轮数前面，顺序反了会报 invalid literal for int()，见 5.2 坑三）。

Q3：ALLOW_PUBLIC_PROJECT_CREATION = False 后脚本建项目全部 400？ 这是参数的真实语义边界：False 会连 REST API 的建项目（POST）与改项目（PUT）一起拦停，API 没有管理口令旁路（源码分支 form.validate() and config.get("ALLOW_PUBLIC_PROJECT_CREATION")，实测回显见 5.3）。解决：需要 API 自动化就保持 True，收口改在 Nginx 层限制来源；或接受 API 不可用。

Q4：HTTP 部署下登录态保存不住（一刷新就掉）？ SESSION_COOKIE_SECURE=True（默认）与纯 HTTP 冲突，浏览器丢弃 Secure Cookie。HTTP 环境改 False；HTTPS 环境保持 True（见 5.2）。

Q5：镜像部署改了 /etc/ihatemoney/ihatemoney.cfg 重启后被打回原形？ 镜像 entrypoint 每次启动用环境变量重写该文件，手工改动必然丢失。改 compose 的 environment: 后 docker compose up -d（参数对应关系见《IHateMoney 7.2.1 Docker Compose 部署指南》第六章环境变量表）。

Q6：配置里那个 SQLACHEMY_ECHO 是拼写错误吗？ 是历史遗留键（正确概念应为 SQLALCHEMY_ECHO），7.2.1 代码只在其默认设置中赋值、无消费点，设不设置都无效果（代码溯源回显见 5.1）。

八、参考链接

• 官方配置文档：https://ihatemoney.readthedocs.io/en/latest/configuration.html
• 官方安装文档：https://ihatemoney.readthedocs.io/en/latest/installation.html
• 源码配置定义（default_settings.py）：https://github.com/spiral-project/ihatemoney/blob/master/ihatemoney/default_settings.py
• 本专栏其他篇目：《IHateMoney 7.2.1 介绍与选型指南》《Ubuntu 22.04 安装 IHateMoney 7.2.1 指南》《IHateMoney 7.2.1 Docker Compose 部署指南》《IHateMoney 7.2.1 API/CLI 使用详解》