Part-DB 2.20.2 配置参数详解

目标：本文系统梳理 Part-DB 2.20.2 的配置体系与全部关键配置参数，覆盖配置的三层优先级、.env.local 环境变量全集、Web 设置页联动、SAML/OAuth2/MCP 等安全相关配置，并给出生产配置模板。内容基于官方配置文档（docs.part-db.de/configuration.html，查询日期 2026-10-24）与 v2.20.2 实例实测。组件背景见 《Part-DB 2.20.2 介绍与选型指南》，部署流程见 《Part-DB 2.20.2 Docker Compose 部署指南》。

一、环境信息

二、配置的三层体系与优先级

Part-DB 的配置入口分三层，优先级从高到低：

1. 环境变量（.env.local 或服务级环境变量）：管理员级别。可覆盖 Web 设置页中的同名项，被覆盖的项在设置页中置灰不可改。另有一批标注「(env only)」的参数只能在此层设置。
2. Web 设置页（存储于数据库）：系统设置页中的常规项，改动即时生效，无需重启服务。
3. 用户个人设置：语言、时区、主题、首选币种四项，用户可在个人设置页自选（默认继承全局值）。

查看当前生效环境变量的官方命令（实例实测输出）：

$ php bin/console debug:dotenv --env=docker

Dotenv Variables & Files
========================

Scanned Files (in descending priority)
--------------------------------------

 * ⨯ .env.local.php
 * ⨯ .env.docker.local
 * ✓ .env.docker
 * ⨯ .env.local
 * ✓ .env

Variables
---------

 ---------------------------------------------- --------------------------------------------- --------------
  Variable                                       Value                                         .env.docker
 ---------------------------------------------- --------------------------------------------- --------------
  ALLOW_ATTACHMENT_DOWNLOADS_FROM_LOCALNETWORK   0                                             n/a
  ALLOW_EMAIL_PW_RESET                           0                                             n/a
  APP_ENV                                        docker                                        n/a
  APP_SECRET                                     d41d1f9b0a3c4e5f87659012abcdef34a1b2c3d4e...  n/a
  DATABASE_EMULATE_NATURAL_SORT                  0                                             n/a
  ...

要点：

• .env.local 优先级高于 .env（官方默认模板不应直接修改，升级时会被覆盖）；永远把自定义配置写到 .env.local。
• 修改 .env.local 后需要重启服务（PHP-FPM）才能生效；Web 设置页改动即时生效。
• 想把某个「env 覆盖」恢复为「页面可改」，执行 php bin/console settings:migrate-env-to-settings 把该值迁入数据库，然后删掉对应环境变量（实测命令帮助如下）：

$ php bin/console settings:migrate-env-to-settings --help
Description:
  Migrates environment variables to stored settings parameters

Usage:
  settings:migrate-env-to-settings [options] [--] [<settings>]

Arguments:
  settings              The class of the setting that should be migrated. If this is not set,
                        the user will be asked which setting should be migrated.

Options:
  -a, --all             Migrate the environment variables of all settings available in the application
      --no-validation   Do not validate the settings before saving them.

• 安全细节：凡是「敏感值被环境变量覆盖」的项（如各类 API Key），Web 设置页上会自动脱敏，仅显示末 2 位与长度，管理员也无法看到全文——防止密钥经浏览器泄漏。

三、参数总览

四、核心参数详解

4.1 应用基础与安全

• APP_SECRET（env only，必改项）：Symfony 用于签名 Cookie、生成 CSRF 令牌等加密操作的秘密钥。官方默认值是公开的，暴露到网络前必须更换，否则攻击者可伪造签名 Cookie 绕过 CSRF 防护；未更换时首页会对管理员显示警告。生成方式：echo "APP_SECRET=$(openssl rand -hex 32)" >> .env.local。
• APP_ENV（env only）：正常使用恒为 prod（官方镜像环境为 docker，行为等同生产）。设为 dev 会开启调试模式并泄漏敏感信息，严禁在公网服务器使用。
• INSTANCE_NAME：实例名，显示在导航栏等处，默认 Part-DB，可改为如 ExampleCorp. Inventory。
• BANNER：首页横幅文本（Markdown 语法）。也可在系统设置页改，或直接编辑 config/banner.md。
• DEPRECATION_LOG_LEVEL（env only，默认 emergency）：弃用日志的最低记录级别；设为 debug 可在 var/log/<env>_deprecations.log 记录全部弃用提示（升级前排障用）。

4.2 区域与币种

• DEFAULT_LANG：全局默认语言（用户未显式选择时），取 en、de、zh_CN 等语言码。
• DEFAULT_TIMEZONE：全局默认时区，如 Asia/Shanghai（完整列表见 IANA tz database）。
• BASE_CURRENCY：内部记账的基础币种（ISO 4217 代码，如 EUR、USD、CNY）。⚠️ 建库后无法真正更改——所有价格内部以基础币种存储；从旧版 Part-DB 迁移时应与旧实例一致。非欧元基础币种需配 FIXER_API_KEY（fixer.io 注册）以自动更新汇率。

4.3 数据库连接

• DATABASE_URL（env only，核心参数）：数据库连接串，三种格式：
  • MySQL/MariaDB：DATABASE_URL=mysql://user:password@127.0.0.1:3306/part-db?serverVersion=8.0
  • PostgreSQL：DATABASE_URL=postgresql://user:password@127.0.0.1:5432/part-db?serverVersion=15（serverVersion=x.y 必填）
  • SQLite：DATABASE_URL=sqlite:///%kernel.project_dir%/var/app.db（%kernel.project_dir% 指向安装根目录）
• DATABASE_MYSQL_USE_SSL_CA（默认 0）：设 1 后 MySQL 连接启用 SSL/TLS，并校验服务端证书（对系统 CA 或随 Part-DB 打包的 CA）。
• DATABASE_MYSQL_SSL_VERIFY_CERT（默认 1）：设 0 关闭证书校验（仅自签调试场景，明令慎用）。
• DATABASE_EMULATE_NATURAL_SORT（默认 0）：数据库不支持自然排序时（SQLite、MariaDB < 10.7）设 1 强制模拟，慢且有怪癖，仅在需要时开启。
• DATABASE_SQLITE_ENFORCE_FOREIGN_KEYS（默认 0）：SQLite 下设 1 强制外键约束（PRAGMA foreign_keys = ON）。默认关闭是为了兼容存量数据；在旧库上开启前先跑 php bin/console partdb:database:check-sqlite-foreign-keys 检查（加 --fix 自动修复违规行）。

4.4 对外地址与反向代理

• DEFAULT_URI（env only）：实例对外主 URL，用于生成邮件链接、SAML 场景等无法从请求推断地址的场合；必须以斜杠结尾，如 https://partdb.example.com/。有反向代理时填代理对外地址。
• TRUSTED_HOSTS（env only）：Host 头白名单正则，防 Host 头攻击。.env.local 中值需单引号包裹：TRUSTED_HOSTS='^(part-db\.example\.invalid)$'；多域名用 | 分隔。未设置时首页对管理员显示安全警告；MCP 端点的 DNS 重绑定防护也依赖该配置。
• TRUSTED_PROXIES（env only）：反向代理来源 IP 段（如 10.0.0.0/8,172.16.0.0/12,192.168.0.0/16），用于正确解析客户端真实 IP。
• REDIRECT_TO_HTTPS（env only）：设 1 后所有 HTTP 请求 301 到 HTTPS。仅当 Web 服务器本身不做跳转时才需要；开启前先确认 HTTPS 可访问。
• NO_URL_REWRITE_AVAILABLE（env only）：仅当 Web 服务器不支持 URL 重写时设 1（URL 会变成 index.php/... 形态），常规部署不用动。

4.5 附件与上传

• ALLOW_ATTACHMENT_DOWNLOADS（0/1）：设 1 允许用户让 Part-DB 直接把外部 URL 文件抓取为本地附件。⚠️ 相当于把服务器可达的一切公网资源开放给用户（包括同网段服务），属于安全敏感项，默认关闭。
• ALLOW_ATTACHMENT_DOWNLOADS_FROM_LOCALNETWORK（默认 0）：进一步允许抓取内网 URL 的文件；信任全部用户且内网安全时才开。
• ATTACHMENT_DOWNLOAD_BY_DEFAULT：设 1 后，新增附件时「下载外部文件」复选框默认勾选（配合上一项使用）。
• ATTACHMENT_SHOW_HTML_FILES：设 1 允许浏览器内直接预览上传的 HTML 附件（已限制恶意函数，仍有风险），0 时按纯文本渲染。
• MAX_ATTACHMENT_FILE_SIZE：Part-DB 侧单个附件上限，默认 100M（支持 K/M/G 后缀）。注意这只是应用限制，还需同步调整 PHP 的 upload_max_filesize 与 post_max_size。

4.6 邮件（全组 env only）

• MAILER_DSN：发件服务 DSN，默认 null://null（不发信）。SMTP 示例：MAILER_DSN=smtp://user:password@smtp.mailserver.invalid:587（完整语法见 Symfony Mailer 文档）。
• EMAIL_SENDER_EMAIL：发件人地址（多数 SMTP 要求与认证账号一致），默认 noreply@partdb.changeme。
• EMAIL_SENDER_NAME：发件人显示名，默认 Part-DB Mailer。
• ALLOW_EMAIL_PW_RESET：设 1 启用「邮件找回密码」，前提是先配好 MAILER_DSN。

4.7 变更审计与历史

• ENFORCE_CHANGE_COMMENTS_FOR：强制填写变更理由的场景列表（逗号分隔，写入事件日志）。可选值：part_edit、part_delete、part_create、part_stock_operation（出入库）、datastructure_edit、datastructure_delete、datastructure_create。留空表示全部可选。
• HISTORY_SAVE_CHANGED_FIELDS：记录「哪些字段被改过」（不含内容）。
• HISTORY_SAVE_CHANGED_DATA：记录变更前数据（可看「改名前是什么」）。
• HISTORY_SAVE_NEW_DATA：记录变更后数据。
• HISTORY_SAVE_REMOVED_DATA：记录被删除的数据。 ⚠️ 要使用「版本回退/查看历史修订」功能，HISTORY_SAVE_CHANGED_FIELDS、HISTORY_SAVE_CHANGED_DATA、HISTORY_SAVE_REMOVED_DATA 三项必须全开；数据量大时这些配置会显著增加数据库体积，按需取舍。

4.8 更新与备份管理

• CHECK_FOR_UPDATES（默认 1）：是否连 GitHub 检查新版本；离线环境设 0。
• DISABLE_WEB_UPDATES（默认 1）：网页端一键更新默认禁用（安全考虑）。设 0 才能在 Update Manager 界面执行更新；CLI 的 php bin/console partdb:update 不受此限制。
• DISABLE_BACKUP_RESTORE（默认 1）：网页端备份恢复默认禁用（恢复是覆盖性破坏操作）。CLI 恢复不受限。
• DISABLE_BACKUP_DOWNLOAD（默认 1）：网页端下载备份默认禁用（备份含密码哈希与密钥等敏感数据）；设 0 后下载仍需确认密码。
• WATCHTOWER_API_URL / WATCHTOWER_API_TOKEN：对接 Watchtower 实现 Update Manager 一键容器更新（仅官方镜像部署形态使用）。

4.9 表格显示

• TABLE_DEFAULT_PAGE_SIZE：表格每页行数，-1 表示不分页全量显示（大数据量勿用）。
• TABLE_PARTS_DEFAULT_COLUMNS：元件表默认列及顺序（逗号分隔）。可用列：name、id、ipn、description、category、footprint、manufacturer、storage_location、amount、supplier、supplier_part_number、minamount、partUnit、partCustomState、addedDate、lastModified、needs_review、favorite、manufacturing_status、manufacturer_product_number、mass、tags、attachments、edit。

4.10 EDA 集成

• EDA_KICAD_CATEGORY_DEPTH：KiCad 插件树中显示的 Part-DB 类别层级深度。默认 0（仅顶层类别）；-1 表示全部元件平铺在单一类别下。层级越深 KiCad 加载越慢，按元件库规模折中。

4.11 OAuth2 与 MCP（AI 集成）

• OAUTH2_ENCRYPTION_KEY（env only）：OAuth2 授权码与刷新令牌的加密钥。默认未设置；生产启用 OAuth2 前必须用 php bin/console partdb:oauth:generate-secret 生成并写入 .env.local。⚠️ 一旦启用不得再改，否则所有在途刷新令牌与授权码全部失效。
• OAUTH_SERVER_ENABLED（默认 0）：启用 OAuth2 授权服务器（/oauth/authorize、/oauth/token、/tools/oauth_clients 管理页、/.well-known/ 发现端点及 OAuth2 Bearer 认证）。关闭时这些端点完全不可达。
• OAUTH_DCR_ENABLED（默认 0）：开放无认证的动态客户端注册（RFC 7591，POST /oauth/register），仅在 OAUTH_SERVER_ENABLED=1 时生效；无论如何管理员都可在 /tools/oauth_clients 手动注册客户端。
• MCP_ENABLED（默认 0）：启用 MCP 服务器（/mcp 路径），供 AI 助手/Agent 查询库存；也可在系统设置 AI 页切换。
• MCP_EDITING_ENABLED（默认 0）：额外开放 MCP 写操作（元件、主数据、库存调整）。⚠️ 未开启时即使 MCP_ENABLED=1，任何用户任何令牌范围（含 FULL）的写调用一律被拒绝，只有只读工具可用。

4.12 SAML 单点登录（全组 env only）

启用前先设好 DEFAULT_URI（SAML 依赖它构造回调）。

• SAML_ENABLED：1 启用后登录页出现 SSO 按钮。
• SAML_BEHIND_PROXY：部署在反向代理后时设 1（否则保持 0）。
• SAML_ROLE_MAPPING：JSON 映射，把 IdP 的 group 属性映射为 Part-DB 组 ID，支持 * 通配；首个匹配生效，高权限组放前面，如 SAML_ROLE_MAPPING='{ "*": 2, "admin": 1, "editor": 3}'。
• SAML_UPDATE_GROUP_ON_LOGIN（默认 1）：每次登录按 SAML 角色刷新用户组；设 0 则只在首次登录时赋组，之后由管理员手工管理。
• IdP 侧四项：SAML_IDP_ENTITY_ID、SAML_IDP_SINGLE_SIGN_ON_SERVICE、SAML_IDP_SINGLE_LOGOUT_SERVICE、SAML_IDP_X509_CERT（base64 证书，以 MIIC 开头 = 结尾），均可从 IdP（如 Keycloak realm）的 metadata XML 或管理界面取到。
• SP 侧三项：SAML_SP_ENTITY_ID（约定为 Part-DB 域名 + /sp）、SAML_SP_X509_CERT（以 MIIC 开头）、SAML_SP_PRIVATE_KEY（以 MIIE 开头；Keycloak 可直接为客户端生成密钥对）。
• 进阶参数在 config/packages/hslavich_onelogin_saml.yaml，⚠️ 该文件不随备份脚本备份，改动需自行备份；镜像部署形态需将其映射为持久卷。

4.13 体验杂项

• SHOW_PART_IMAGE_OVERLAY：0 关闭元件图片悬停放大浮层。
• KEYBINDINGS_SPECIAL_CHARS_ENABLED：0 关闭 Alt+键 特殊字符快捷键（与输入法冲突时用）。
• USE_GRAVATAR：1 时未设头像的用户使用 gravatar.com 头像（浏览器需访问第三方，有隐私考量）。
• ERROR_PAGE_ADMIN_EMAIL（env only）：错误页显示的管理员联系邮箱。
• ERROR_PAGE_SHOW_HELP（env only，默认 1）：0 关闭错误页上的排障提示（避免终端用户看到）。
• DEMO_MODE（env only）：演示模式，禁止用户改密码和设置；普通部署不要开。
• DISABLE_YEAR2038_BUG_CHECK（env only）：32 位系统上的 2038 检查开关；64 位系统不受影响。
• FIXER_API_KEY：fixer.io 汇率 API Key（基础币种非欧元时用于自动汇率）。
• IPN_* 系列：内部料号（IPN）建议规则——IPN_SUGGEST_REGEX 全局正则约束格式、IPN_SUGGEST_REGEX_HELP 自定义帮助文案、IPN_AUTO_APPEND_SUFFIX 重复 IPN 自动追加自增后缀、IPN_SUGGEST_PART_DIGITS 自增位数、IPN_USE_DUPLICATE_DESCRIPTION 按描述匹配已有料号推算下一个号。
• LOCK_DSN（默认 flock）：Symfony 锁存储，PostgreSQL 可用 postgresql+advisory://db_user:db_password@localhost/db_name。
• CORS_ALLOW_ORIGIN（默认 '^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$'）：跨域白名单，供浏览器直连 API 的前端使用，按需收紧/放宽。

五、Web 设置页与 parameters.yaml

Web 设置页（System → Settings）覆盖绝大多数常规项：默认语言/时区/币种、实例名、横幅、附件策略、代理与可信主机、更新检查、日志与历史、IPN 规则、EDA/KiCad、OAuth2/MCP 开关等。被环境变量覆盖的项呈灰色，悬停可见对应变量名；带敏感值的项自动脱敏（只显示末 2 位与长度）。

config/parameters.yaml 是更底层的框架级配置，官方明确「通常不需要动，且升级时可能需要手工合并」，改后必须 php bin/console cache:clear。可用项：

• partdb.locale_menu：语言选择器展示的语言码列表（首个为默认）。
• partdb.gdpr_compliance（默认 true）：日志中的 IP 自动匿名化（去末字节，欧盟 GDPR 合规）。
• partdb.sidebar.items：默认侧栏面板及数量。
• partdb.sidebar.root_node_enable / partdb.sidebar.root_expanded：侧栏树根节点显示/默认展开。
• partdb.available_themes：用户可选主题列表。

六、生产配置模板

以下为一份多用户生产环境（MySQL + 反向代理 + 邮件）的 .env.local 起点，直接复制后按注释替换：

# ===== 安全（必改）=====
APP_SECRET=<openssl rand -hex 32 生成>
TRUSTED_HOSTS='^(part-db\.example\.com)$'
TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
REDIRECT_TO_HTTPS=1
DEFAULT_URI="https://part-db.example.com/"

# ===== 数据库 =====
DATABASE_URL=mysql://partdb:<强密码>@127.0.0.1:3306/part-db?serverVersion=8.0
DATABASE_MYSQL_USE_SSL_CA=0

# ===== 基础体验 =====
DEFAULT_LANG=zh_CN
DEFAULT_TIMEZONE=Asia/Shanghai
BASE_CURRENCY=CNY
INSTANCE_NAME="示例公司元件库"

# ===== 附件 =====
ALLOW_ATTACHMENT_DOWNLOADS=0
MAX_ATTACHMENT_FILE_SIZE=100M

# ===== 邮件 =====
MAILER_DSN=smtp://partdb:<SMTP密码>@smtp.example.com:587
EMAIL_SENDER_EMAIL=partdb@example.com
EMAIL_SENDER_NAME="Part-DB"
ALLOW_EMAIL_PW_RESET=1

# ===== 更新与备份（保持网页端高风险操作默认关闭）=====
CHECK_FOR_UPDATES=1
DISABLE_WEB_UPDATES=1
DISABLE_BACKUP_RESTORE=1
DISABLE_BACKUP_DOWNLOAD=1

# ===== 审计 =====
ENFORCE_CHANGE_COMMENTS_FOR=part_stock_operation,part_delete
HISTORY_SAVE_CHANGED_FIELDS=1
HISTORY_SAVE_CHANGED_DATA=1
HISTORY_SAVE_REMOVED_DATA=1
HISTORY_SAVE_NEW_DATA=1

七、常见问题

• 改了 .env.local 不生效：环境变量在进程启动时读取，重启服务（PHP-FPM / 对应服务单元）后再验证；用 debug:dotenv 确认加载顺序里 .env.local 是否被扫描到。
• 设置页某项灰色改不了：该项被环境变量覆盖。改环境变量，或 settings:migrate-env-to-settings 迁入数据库后删除环境变量。
• BASE_CURRENCY 建库后能改吗：不能真正改。所有价格内部按基础币种存储，只能通过重新迁移数据的代价解决，务必建库前定对。
• SAML 登录跳转出错：90% 是 DEFAULT_URI 未设置或末尾缺斜杠；其次检查 SAML_BEHIND_PROXY 与代理层传递的 Host/X-Forwarded 头。
• API 想开但页面没有 token 入口：除系统开关外，用户本身需要「Access API / Manage API tokens」权限位（管理员在用户管理中勾选），见 API 篇的权限章节。
• 大附件上传失败：MAX_ATTACHMENT_FILE_SIZE 只是应用层限制，还需调大 PHP 的 upload_max_filesize、post_max_size。

八、参考链接

• 官方配置文档：https://docs.part-db.de/configuration.html
• 官方默认 .env 模板：https://github.com/Part-DB/Part-DB-server/blob/master/.env
• SAML/反向代理官方指南：https://docs.part-db.de/installation/reverse-proxy.html
• 本系列其他篇章：
  • 选型与功能：《Part-DB 2.20.2 介绍与选型指南》
  • 部署流程：《Part-DB 2.20.2 Docker Compose 部署指南》
  • API 集成：《Part-DB 2.20.2 API 使用详解》