InvoicePlane 1.7.2 配置参数详解

目标：系统讲清 InvoicePlane 1.7.2 的全部配置参数——它分为「ipconfig.php 常量层」与「后台系统设置层」两层，各自管什么、怎么查看、怎么修改、安全默认值是什么，并给出生产配置模板与排障 FAQ。本文在 Ubuntu 22.04 + Docker Compose 部署的 1.7.2 实测环境逐项核实（2026-10-24）。部署过程见《InvoicePlane 1.7.2 Docker Compose 部署指南》，软件定位见《InvoicePlane 介绍与选型指南》。

一、环境信息

项目	值
软件版本	InvoicePlane 1.7.2（官方 git tag v1.7.2，参数清单核实自官方 `ipconfig.php.example` 与 `.github/docs/CONTAINER_DEPLOYMENT.md`）
实测环境	Ubuntu 22.04（内核 6.8.0-138-generic）+ Docker Compose v5.5.1 部署
数据库	MariaDB 11（实测服务端 11.8.9-MariaDB-ubu2404）
应用访问	http://192.168.146.128:8128（实测环境 `IP_URL`）
后台演示账号	admin@example.com / q1w2e3r4（仅演示环境，生产必须更换）
系统设置实证	后台「系统设置」八类参数的存储键名取自官方设置页源码（settings 模块视图），实存值取自实测库 `ip_settings` 表

二、前置条件

一套已部署完成的 InvoicePlane 1.7.2（经典 PHP 站点或 Compose 部署均可；Compose 部署步骤见本系列部署篇）。
经典安装需能编辑站点根目录的 ipconfig.php；容器部署需能编辑 compose 文件并 docker compose up -d 重建，且可进入容器核对配置。
一名后台管理员账号（用于系统设置层操作；演示环境为 admin@example.com / q1w2e3r4）。

三、参数查看与修改方式

3.1 配置分层总览

InvoicePlane 的配置分两层，职责不同、修改入口不同：

层	存储位置	管什么	修改入口
ipconfig 常量层	站点根 `ipconfig.php`（PHP 常量/环境变量生成）	站点地址、数据库连接、会话与安全策略、安装开关、模板白名单、限流阈值、加密密钥	经典安装：手工编辑文件；容器部署：compose 环境变量（由 entrypoint 生成该文件）
系统设置层	数据库 `ip_settings` 表（键值对）	业务参数：编号规则、到期天数、邮件 SMTP、发票/报价模板、税率、在线支付网关、cron_key、eInvoice	后台「系统设置」八个标签页（无需改文件/重启）

💡 判断口诀："怎么连、怎么防、怎么装"看 ipconfig；"怎么编号、怎么发信、怎么开票"看系统设置。改系统设置立即生效；改 ipconfig 常量层在经典安装下需刷新即生效（CI 常量进程内加载），在容器部署下需重建容器。

3.2 容器部署路径（推荐，实测）

配置唯一事实源是 compose 的 environment:。修改 → 重建两步：

cd /opt/invoiceplane
vi compose.yaml            # 修改 environment 段
docker compose up -d       # 重建生效（数据卷保留，迁移自动执行）

entrypoint 每次启动都会按环境变量重写容器内 /var/www/html/ipconfig.php——直接进容器改该文件重启即丢（实测确认该行为）。核对当前生效配置：

docker exec invoiceplane-172-stack-app-1 cat /var/www/html/ipconfig.php

实测输出节选（本环境演示值）：

IP_URL=http://192.168.146.128:8128
ENABLE_DEBUG=false
CI_ENV=production
X_FRAME_OPTIONS=SAMEORIGIN
SESS_REGENERATE_DESTROY=false
DEFAULT_LANGUAGE=english
DISABLE_SETUP=true
REMOVE_INDEXPHP=true
DB_HOSTNAME=db
DB_USERNAME=invoiceplane
DB_PASSWORD=invoiceplane
DB_DATABASE=invoiceplane
DB_PORT=3306
SETUP_COMPLETED=true

3.3 经典安装路径

直接编辑站点根 ipconfig.php（文件首行 <?php exit(...) 防直读保护保留），对照官方模板 ipconfig.php.example 逐项修改。安装未完成前保持 SETUP_COMPLETED=false，完成后手工置 true（或让安装向导写入）。

3.4 系统设置路径（后台）

后台「系统设置」共八个标签页（官方设置模块源码视图清单）：常规（General）、发票（Invoices）、报价（Quotes）、邮件（Email）、在线支付（Online Payment）、税率（Taxes）、项目与任务（Projects & Tasks）、更新（Updates）。所有键值实时存 ip_settings 表，实测直查（演示实例当前键值，节选）：

docker exec invoiceplane-172-stack-db-1 mariadb -uroot -proot invoiceplane \
  -e "SELECT setting_key, setting_value FROM ip_settings ORDER BY setting_key"

setting_key                    setting_value
cron_key                       LH4UcspYjfyhn2da
date_format                    Y-m-d
default_invoice_group          4
emails_pdf_attachment          1
enable_permissive_search_clients  0
einvoicing                     0
invoice_default_payment_method 2
invoices_due_after             30
mark_invoices_sent_pdf         0
pdf_invoice_footer
read_only_toggle               paid
...

⚠️ 系统设置仅存显式改过的键；未改的项走代码内置默认值，ip_settings 为空不代表"没有配置"。

四、参数总览（ipconfig 层全量清单）

官方 ipconfig.php.example（v1.7.2）共 39 个参数，按分组全列如下（默认值取自官方模板）：

分组	参数 = 官方默认值
站点与运行模式	`IP_URL=`（必填）、`CI_ENV=production`、`ENABLE_DEBUG=false`
数据库连接	`DB_HOSTNAME=`、`DB_USERNAME=`、`DB_PASSWORD=`、`DB_DATABASE=`、`DB_PORT=`（官方模板另有注释态 `#DB_ENCRYPT=`，用于启用传输层加密）
加密	`ENCRYPTION_KEY=`（必填）、`ENCRYPTION_CIPHER=AES-256`
安装控制	`DISABLE_SETUP=false`、`SETUP_COMPLETED=false`、`REMOVE_INDEXPHP=false`
会话	`SESS_SAVE_PATH=`、`SESS_COOKIE_NAME=ip_session`、`SESS_TABLE_NAME=ip_sessions`、`SESS_EXPIRATION=864000`、`SESS_MATCH_IP=true`、`SESS_REGENERATE_DESTROY=true`
安全头与隐私	`X_FRAME_OPTIONS=SAMEORIGIN`、`ENABLE_X_CONTENT_TYPE_OPTIONS=true`、`SEC_STRIP_EXIF_FROM_IMAGES=false`
业务风险开关	`LEGACY_CALCULATION=true`、`ENABLE_INVOICE_DELETION=false`、`DISABLE_READ_ONLY=false`
密码重置限流	`PASSWORD_RESET_IP_MAX_ATTEMPTS=5`、`PASSWORD_RESET_IP_WINDOW_MINUTES=60`、`PASSWORD_RESET_EMAIL_MAX_ATTEMPTS=3`、`PASSWORD_RESET_EMAIL_WINDOW_HOURS=1`、`PASSWORD_RESET_TOKEN_EXPIRY_MINUTES=15`
模板体系	`CUSTOM_TEMPLATES_FOLDER=`、`CUSTOM_INVOICE_TEMPLATES_PDF=`、`CUSTOM_INVOICE_TEMPLATES_PUBLIC=`、`CUSTOM_QUOTE_TEMPLATES_PDF=`、`CUSTOM_QUOTE_TEMPLATES_PUBLIC=`
Sumex 医疗发票	`SUMEX_SETTINGS=false`、`SUMEX_URL=`

⚠️ 官方两处默认值不一致（实测核对结论）：①LEGACY_CALCULATION 官方 ipconfig 模板默认 true（向后兼容旧税额算法），但容器环境变量契约默认 false（合规要求）——需要生成欧盟电子发票 XML 的环境必须显式设 false，见 5.2；②SESS_REGENERATE_DESTROY 官方文档标注默认 true，entrypoint 脚本缺省实际回退 false——生产建议显式设 true。两处都建议不依赖默认值、显式写明。

五、核心参数详解（ipconfig 层）

5.1 站点与运行模式

IP_URL：站点对外完整地址（无尾部斜杠）。决定登录跳转、公开链接、邮件内链接的生成。实测设置 http://192.168.146.128:8128 时，访问首页返回 307 -> http://192.168.146.128:8128/sessions/login——IP_URL 与实际访问地址不一致时跳转即错。生产上改为 https://invoices.example.com 形式。

CI_ENV：CodeIgniter 运行环境。production（默认）抑制错误回显；排障可临时 development。

ENABLE_DEBUG：true 时输出高级调试日志（含 SQL），排障完毕立即关回 false，避免泄露敏感信息。

5.2 数据库与加密、税额计算口径

DB_* 五件套：连接信息，容器部署下 DB_HOSTNAME 填服务名走内网。官方模板注释态 DB_ENCRYPT 可开启数据库传输加密（自管证书场景按需）。

ENCRYPTION_KEY / ENCRYPTION_CIPHER：应用层加密密钥与算法（AES-256）。用于加密存量敏感设置。密钥一经使用不可随意更换——更换后既有加密数据无法解密。生成方式：

openssl rand -base64 32

5Qj8mH2xLp9vRk3sT7wY1uN6cZ4aE0bD+fGhIjKlMnO=

LEGACY_CALCULATION：税额/折扣计算口径开关，是最容易被忽略的合规参数：

取值	行为	适用
`true`（ipconfig 模板默认）	沿用 1.6.3 前的旧计算算法，保证与历史账单口径一致	老账套延续、无电子发票合规要求
`false`（容器环境变量默认）	新版计算口径（税额逐条舍入），电子发票 XML 金额校验可过	生成 Factur-X/UBL 电子发票必须；新部署建议

官方文档明确：开启 LEGACY_CALCULATION=true 的实例无法生成合规电子发票 XML。

5.3 安装控制三开关

DISABLE_SETUP / SETUP_COMPLETED / REMOVE_INDEXPHP：分别关闭 Web 安装向导入口、标记安装已完成、URL 去除 index.php。容器部署下由 entrypoint 自动置 DISABLE_SETUP=true、SETUP_COMPLETED=true、REMOVE_INDEXPHP=true（实测生成文件确认），防止向导重入攻击；经典安装需在安装完成后自行确认这两项为 true。

5.4 会话参数

参数	默认	说明与建议
`SESS_SAVE_PATH`	空（PHP 临时目录）	会话文件目录；建议显式设到持久化目录（容器部署已在 storage 卷内）
`SESS_COOKIE_NAME`	`ip_session`	Cookie 名，一般不动
`SESS_TABLE_NAME`	`ip_sessions`	会话表名
`SESS_EXPIRATION`	`864000`（10 天）	会话有效期（秒）；0 = 关浏览器即失效。内网工具可缩短到 1 天
`SESS_MATCH_IP`	`true`	会话绑定客户端 IP；NAT/移动办公场景频繁掉线时设 `false`（安全性略降）
`SESS_REGENERATE_DESTROY`	模板 `true` / entrypoint 缺省 `false`	会话 ID 重建时销毁旧会话（防会话固定）；生产显式 `true`

5.5 安全头与业务风险开关

参数	默认	说明
`X_FRAME_OPTIONS`	`SAMEORIGIN`	防点击劫持响应头，一般不动
`ENABLE_X_CONTENT_TYPE_OPTIONS`	`true`	nosniff 防护
`SEC_STRIP_EXIF_FROM_IMAGES`	`false`	上传图片剥离 EXIF（含 GPS/时间隐私）；客户上传图片的场景建议 `true`
`ENABLE_INVOICE_DELETION`	`false`	允许"彻底删除"发票（含已编号账单）；财务留痕要求下保持 `false`
`DISABLE_READ_ONLY`	`false`	关闭已发送发票的只读锁定；除非确需事后编辑，保持 `false`（锁定是审计底线，锁定时点由系统设置 `read_only_toggle` 决定，实测当前为 `paid`）

5.6 密码重置限流五参数

PASSWORD_RESET_IP_MAX_ATTEMPTS=5（60 分钟内按 IP）、PASSWORD_RESET_EMAIL_MAX_ATTEMPTS=3（1 小时内按邮箱）、PASSWORD_RESET_TOKEN_EXPIRY_MINUTES=15（重置令牌有效期）。默认值已是合理基线，暴力破解高暴露面（公网）可收紧窗口。实测行为：超限后重置请求被拒并记录到 ip_login_log 表。

5.7 模板体系五参数（防 RCE 关键设计）

参数	说明
`CUSTOM_TEMPLATES_FOLDER`	自定义模板根目录（绝对路径），内部必须含 `invoice_templates/pdf
`CUSTOM_INVOICE_TEMPLATES_PDF`	自定义 PDF 发票模板白名单（逗号分隔模板名，不含 .php）
`CUSTOM_INVOICE_TEMPLATES_PUBLIC`	自定义网页发票模板白名单
`CUSTOM_QUOTE_TEMPLATES_PDF`	自定义 PDF 报价模板白名单
`CUSTOM_QUOTE_TEMPLATES_PUBLIC`	自定义网页报价模板白名单

规则（官方安全设计）：模板必须在白名单登记才出现在界面下拉框，文件系统永不扫描；模板名仅允许字母/数字/空格/连字符/下划线，含空格需给整个值加引号；entrypoint 会自动在挂载目录写入 .htaccess（Deny from all）阻止 HTTP 直读模板源码。这套"白名单 + 结构固定 + 目录禁读"组合是 1.7.x 修复模板上传 RCE 的核心。

5.8 Sumex 瑞士医疗发票

SUMEX_SETTINGS=false（默认关闭）。启用后支持瑞士医疗账单（TARMED）格式，SUMEX_URL 填 Sumex XML→PDF 转换服务地址。非瑞士医疗场景保持关闭。

六、系统设置参数详解（ip_settings 层）

以下键名逐项核实自官方设置页源码，⚠️ 处为实测库中确认的实际值。

6.1 常规页（General）

设置	说明
CRON Key（cron_key） ⚠️	循环发票 cron 端点的鉴权密钥。安装时自动生成 16 位随机令牌（官方 `generate_secure_token(8)`，实测当前值 `LH4UcspYjfyhn2da`）；常规页提供"Generate"按钮一键重生成（走 `settings/ajax/get_cron_key`）。泄露即可能被外部触发循环开票，泄露后立即重生成
日期格式（date_format） ⚠️	发票显示与 PDF 日期格式，实测 `Y-m-d`
语言/本地化	界面语言、货币、金额格式（千分位/小数位）
启用在线支付	与"在线支付页"联动，开启后公开链接出现支付按钮

6.2 发票页（Invoices）

设置键	说明
`default_invoice_group` ⚠️	默认发票编号分组（编号规则引擎入口，规则本体在"发票分组"模块维护；实测 `4`）
`invoices_due_after` ⚠️	发票默认到期天数，实测 `30`（新发票 date_due = 开票日 + 30 天，实测生成账单符合）
`generate_invoice_number_for_draft`	草稿即编号 or 发送时编号；发送时编号可避免草稿占号
`mark_invoices_sent_pdf`	客户下载 PDF 时是否自动标记已发送，实测 `0`
`invoice_pre_password`	PDF 打开密码前缀（可选）
`pdf_watermark`	PDF 水印（如盖章草稿）
`einvoicing` ⚠️	电子发票开关（Factur-X/UBL 生成入口），实测 `0`；开启后发票页可选 XML 输出。⚠️ 依赖 `LEGACY_CALCULATION=false`
`pdf_invoice_template`（及其 `_paid`/`_overdue` 变体）	按状态选用不同 PDF 模板（正常/已付/逾期）
`automatic_email_on_recur`	循环发票生成后自动邮件开关；开启前提：邮件页 SMTP 已配好。实测未开启（无该键）
`invoice_default_payment_method` ⚠️	新发票默认收款方式，实测 `2`
`default_invoice_terms`	新发票默认条款文本
`read_only_toggle` ⚠️	只读锁定时点（sent/paid 等），实测 `paid`
`email_invoice_template`	发票邮件正文用的邮件模板（邮件模板模块维护）

6.3 邮件页（Email）

设置键	说明
`email_send_method`	发信通道：`phpmail`（PHP mail()）/ `sendmail` / `smtp`。容器部署下 phpmail 常不可用，推荐 smtp
`smtp_server_address` / `smtp_port`	SMTP 主机与端口（465/587 等）
`smtp_authentication` / `smtp_username` / `smtp_password`	SMTP 认证三件套（密码加密存储）
`smtp_security`	连接加密：`ssl` / `tls`（STARTTLS）
`smtp_verify_certs`	TLS 证书校验；自签名内部中继可关，公网保持校验
`smtp_mail_from`	发件人地址
`email_pdf_attachment`	发信自动附 PDF，实测 `1`（emails_pdf_attachment 键名，行为同一项）

6.4 在线支付页（Online Payment）

以网关卡片形式配置内置支付渠道（1.7.2 内置 PayPal 与 Stripe，回调由 guest 模块 gateways 控制器承接）：逐网关开关 + 凭据（Stripe 密钥、PayPal 商户配置），开启后客户在公开链接页可直接付款，收款自动登记到 payments。与常规页"启用在线支付"联动。⚠️ 实测环境未配置任何网关（键不存在）。

6.5 其余标签页

报价页（Quotes）：报价编号分组、报价有效期天数、mark_quotes_sent_pdf、报价邮件模板等，结构与发票页对应。
税率页（Taxes）：默认税率、全局税率应用模式（全局税 vs 条目税，与 LEGACY_CALCULATION 口径相关）。
项目与任务页（Projects & Tasks）：任务计时费率默认值等。
更新页（Updates）：检查版本更新、显示当前版本（实测当前 1.7.2）。

七、生产配置模板

7.1 生产 compose 环境变量模板（直接替换即用）

    environment:
      IP_URL: https://invoices.example.com          # 实际对外地址
      DB_HOSTNAME: db
      DB_USERNAME: invoiceplane
      DB_PASSWORD: "<openssl rand -base64 32>"
      DB_DATABASE: invoiceplane
      ENCRYPTION_KEY: "<openssl rand -base64 32>"   # 一经使用勿换
      DEFAULT_LANGUAGE: "chinese"                   # 全新安装生效
      DEFAULT_ADMIN_EMAIL: root@example.com         # 首次初始化后改密
      DEFAULT_ADMIN_PASSWORD: "<强密码>"
      DEFAULT_ADMIN_NAME: admin
      # —— 安全基线 ——
      SESS_REGENERATE_DESTROY: "true"               # 显式设，勿依赖缺省
      SESS_MATCH_IP: "true"
      COOKIE_SECURE: "true"                         # HTTPS 反代后开启
      SEC_STRIP_EXIF_FROM_IMAGES: "true"
      ENABLE_DEBUG: "false"
      CI_ENV: "production"
      LEGACY_CALCULATION: "false"                   # 需 eInvoice 必设 false
      ENABLE_INVOICE_DELETION: "false"
      DISABLE_READ_ONLY: "false"
      # —— 可选：自定义模板白名单 ——
      CUSTOM_TEMPLATES_FOLDER: /var/www/html/templates/
      CUSTOM_INVOICE_TEMPLATES_PDF: "default"

7.2 上线必改清单

#	项	动作
1	管理员密码	首登即改（演示值 admin@example.com/q1w2e3r4 不可外泄到生产）
2	`ENCRYPTION_KEY` / `DB_PASSWORD` / `MARIADB_ROOT_PASSWORD`	强随机值替换
3	HTTPS	反代终结 TLS + `COOKIE_SECURE=true` + `IP_URL` 改 https
4	`LEGACY_CALCULATION`	新部署显式 `false`（除非必须延续旧口径）
5	`SESS_REGENERATE_DESTROY`	显式 `true`
6	SMTP	邮件页配 smtp（开启自动发信/密码重置的前提）
7	cron_key	上线后重生成一次（常规页 Generate 按钮）
8	备份	数据库 dump + uploads 卷计划任务

7.3 内存/磁盘基线（官方镜像实测）

场景	建议
单机自用（<10 客户，低频开票）	应用容器内存限制 512MB、数据库 512MB；磁盘 5GB 起
小微企业常规（数十至数百客户）	各 1GB；磁盘随附件增长预留 10GB+；PDF 生成高峰吃内存，批量发信建议限速
数据落盘	三数据卷（uploads/storage/db）纳入备份；DB 卷优先

八、常见问题（FAQ）

Q1：改了容器内 ipconfig.php，重启后被"还原"？ 容器部署下该文件每次启动由 entrypoint 按环境变量重写（3.2 实测确认）。正确做法：改 compose environment: 后 docker compose up -d。

Q2：管理员密码忘了，SMTP 又没配，怎么恢复？ 密码重置依赖邮件通道，SMTP 未配则无法走邮件重置；create_default_user 检测到已有用户会跳过（不覆盖）。应急恢复路径：用容器内 PHP 生成 bcrypt 哈希后更新 ip_users（实测哈希生成）：

docker exec invoiceplane-172-stack-app-1 php -r "echo password_hash('新密码', PASSWORD_BCRYPT), PHP_EOL;"

$2y$10$qgo/DhCPW.LZR/AgjBeQ6uH12mpDgt.Vr7AmIjIBTT1zkppQecx9m

docker exec invoiceplane-172-stack-db-1 mariadb -uroot -proot invoiceplane \
  -e "UPDATE ip_users SET user_password='上一步哈希' WHERE user_email='admin@example.com'"

⚠️ 这是高风险管理操作（绕过应用审计），仅在唯一管理员锁定时使用；平时用后台用户管理页重置他人密码。

Q3：设置了循环发票"今天"生成却没跑？ 核对容器时区：entrypoint/apache 默认 UTC，date(NOW()) 按 UTC 口径比较 recur_next_date。本环境实测：按北京时间设 10-24 到期、UTC 仍为 10-23 时不触发，改为 10-23 后立即生成。两种修法：按 UTC 设定日期，或给服务加 TZ: Asia/Shanghai 环境变量统一时区。端点触发与限流机制的完整实测见《InvoicePlane 1.7.2 常用 CLI 命令与任务调度详解》。

Q4：SESS_MATCH_IP=true 用户频繁掉线？ 会话与客户端 IP 绑定，客户端经 NAT/代理出口 IP 变化即失效。内网多出口或移动办公环境设 SESS_MATCH_IP: "false"，同时用 HTTPS + COOKIE_SECURE=true 补足传输安全。

Q5：上传了自定义 PDF 模板但下拉框里没有？ 未登记白名单。模板 .php 放进 CUSTOM_TEMPLATES_FOLDER 对应层级后，必须把模板名（不含 .php）加进 CUSTOM_INVOICE_TEMPLATES_PDF（PDF 用）或 CUSTOM_INVOICE_TEMPLATES_PUBLIC（网页用），文件系统不自动扫描。命名含空格时环境变量值整体加引号。

Q6：电子发票 XML 报金额校验错？ LEGACY_CALCULATION=true 的旧税额口径与 Factur-X/UBL 校验规则冲突。设为 false 并复核历史账单口径后重试（见 5.2）。

Q7：开启 ENABLE_DEBUG 排障后忘记关？ 以日志审查习惯兜底：每次排障后立即 ENABLE_DEBUG: "false" 并重建；线上巡检脚本可 grep compose 文件确认无 DEBUG 残留。

九、参考链接

官方参数模板：主仓库 ipconfig.php.example（v1.7.2 源码内；2026-10-24 逐项核对）
官方容器环境变量契约：主仓库 .github/docs/CONTAINER_DEPLOYMENT.md（v1.7.2 源码内；2026-10-24 核对）
官方主仓库：https://github.com/InvoicePlane/InvoicePlane （v1.7.2 tag；2026-10-24 查询）
官方 Wiki（安装与设置说明）：https://wiki.invoiceplane.com/ （2026-10-24 查询）
系统设置实证来源：设置模块视图 partial_settings_general/invoices/email/...php 与实测库 ip_settings 表（2026-10-24）
部署过程与运维：《InvoicePlane 1.7.2 Docker Compose 部署指南》
软件定位与选型：《InvoicePlane 介绍与选型指南》
调度端点、CLI 路由与定时任务落地：《InvoicePlane 1.7.2 常用 CLI 命令与任务调度详解》