Penpot 配置参数详解

目标：把 Penpot 2.18.5 官方 Compose 部署形态下的全部配置项讲透——三层配置体系（.env / 编排锚点 / 服务级变量）、每个 PENPOT_* 参数的取值与影响、功能旗标（flags）全表、以及「改了之后如何验证生效」。所有默认值均取自官方 tag 2.18.5 编排文件与官方配置文档（help.penpot.app/technical-guide/configuration/，2026-10-28 快照），生效验证来自真实栈实测。部署过程见《Penpot Docker Compose 部署实战》。

一、环境信息

实测栈：Penpot 2.18.5 官方 Compose 编排 8 服务（frontend/backend/exporter/admin-console/mcp/postgres:15/valkey:8.1/mailpit:v1），2026-10-28 运行中。
参数来源一：官方编排文件 docker/images/docker-compose.yaml（tag 2.18.5，与本地部署文件逐行 diff 过）。
参数来源二：官方配置文档页快照（2026-10-28 抓取，含全部 PENPOT_* 变量说明）。
验证方法：改参数 → docker compose up -d 重建 → 看后端 welcome to penpot 日志行的 flags/version 回显。

二、配置体系总览

Penpot 的配置分布在两层四处，改之前先分清改的是哪一层：

层	文件/位置	作用域	典型内容
环境变量层	`/opt/penpot/deploy/.env`	编排内所有 `${VAR}` 引用	`PENPOT_VERSION`、`PENPOT_SECRET_KEY`
编排锚点层	`docker-compose.yaml` 顶部 `x-flags`/`x-uri`/`x-database` 等 YAML 锚点	被 4 个服务共享引用	`PENPOT_FLAGS`、`PENPOT_PUBLIC_URI`、数据库三件套
服务变量层	各服务 `environment:` 段	单个服务	backend 的 SMTP/存储、exporter 的并发参数
（数据库侧）	postgres 服务 environment	仅 PostgreSQL 初始化	`POSTGRES_DB/USER/PASSWORD`、`POSTGRES_INITDB_ARGS`

关键机制：YAML 锚点（如 *penpot-flags）被 frontend/backend/exporter 共同引用，改一处全栈生效；而 PENPOT_SECRET_KEY 这类通过 ${PENPOT_SECRET_KEY:-默认值} 解析的变量，实际值来自 .env 文件。

生效验证最直接的手段是后端首行日志（实测回显）：

penpot-backend-1  | [2026-10-27 17:33:22.488] I app.main - hint="welcome to penpot", flags="backend-openapi-doc,...,admin-console,backend-worker,telemetry,render-wasm-dpr,mcp,smtp,component-thumbnails,registration,prepl-server,...", worker?=true, version="2.18.5-RC1"

flags= 把当前全部生效旗标打印出来，是确认旗标改动是否生效的第一入口。

三、核心参数逐项详解

3.1 版本与密钥

参数	默认值	说明
`PENPOT_VERSION`	`2.18`（编排内 `${PENPOT_VERSION:-2.18}`）	全栈版本号，8 个 Penpot 服务统一引用。生产必须显式固定（写 `.env`），否则随 `latest` 漂移
`PENPOT_SECRET_KEY`	`change-this-insecure-key`	会话、邀请等子系统的派生主键。官方建议 `python3 -c "import secrets; print(secrets.token_urlsafe(64))"` 生成 512 位随机串。投产前必改；改换会使全部现有会话失效
`PENPOT_PUBLIC_URI`	`http://localhost:9001`	对外访问地址。必须与浏览器实际访问的协议+域名+端口完全一致；它决定邮件里的链接、Cookie 作用域与前端资源寻址。上反代后改为 `https://penpot.example.com`

⚠️ 注意：PENPOT_PUBLIC_URI 是新手第一坑。部署时把端口从 9001 改成 8140 却忘了同步改 PUBLIC_URI，会出现页面能开但登录后异常的怪象。实测本例改为 http://localhost:8140。

3.2 数据库（单库，仅支持 PostgreSQL）

参数	默认值	说明
`PENPOT_DATABASE_URI`	`postgresql://penpot-postgres/penpot`	连接串（主机名/库名）。主机名即官方编排里的数据库服务名
`PENPOT_DATABASE_USERNAME`	`penpot`	库用户
`PENPOT_DATABASE_PASSWORD`	`penpot`	库密码。与 postgres 服务侧 `POSTGRES_PASSWORD` 两处必须同步修改

官方明确 Penpot 仅支持 PostgreSQL（自托管文档建议 15+，官方编排固定 postgres:15，带 POSTGRES_INITDB_ARGS=--data-checksums 数据校验和初始化）。数据库块由 backend 与 admin-console 两个服务共享引用。

3.3 对象存储（可插拔）

参数	默认值	说明
`PENPOT_OBJECTS_STORAGE_BACKEND`	`fs`	用户上传资产（图片/导出产物等）的存储后端，`fs`（文件系统）或 `s3`（任意 S3 兼容，含 MinIO）
`PENPOT_OBJECTS_STORAGE_FS_DIRECTORY`	`/opt/data/assets`	fs 后端的存放目录（官方编排挂接到 `penpot_assets` 数据卷）
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`	空	s3 后端凭据
`PENPOT_OBJECTS_STORAGE_S3_ENDPOINT`	空	S3 兼容服务地址（如 MinIO）
`PENPOT_OBJECTS_STORAGE_S3_BUCKET`	空	桶名
`PENPOT_OBJECTS_STORAGE_S3_REGION`	空	区域（官方文档补充项）

💡 技术拓展：官方配置文档原话——「These settings are equally useful if you have a Minio storage system」。自托管团队把资产从 fs 切到 MinIO 只需改这一组变量并重启 backend/frontend；切之前注意先同步存量文件。备份策略差异（卷快照 vs 桶同步）见《Penpot 常用命令与运维实战》。

另有 PENPOT_FILE_DATA_BACKEND（官方文档，2026-10-28 快照）：设计文件数据的存放后端，可选 legacy-db / db / storage，官方示例值为 db——决定文件数据放关系库还是对象存储，影响备份粒度（默认编排未显式设置，走内置默认）。

3.4 SMTP / 邮件

参数	默认值（官方编排）	说明
`PENPOT_SMTP_HOST`	`penpot-mailpit`	SMTP 主机。默认指向测试邮箱服务，仅本机调试用
`PENPOT_SMTP_PORT`	`1025`	SMTP 端口
`PENPOT_SMTP_DEFAULT_FROM`	`no-reply@example.com`	发件人
`PENPOT_SMTP_DEFAULT_REPLY_TO`	`no-reply@example.com`	回复地址
`PENPOT_SMTP_USERNAME` / `PENPOT_SMTP_PASSWORD`	空	认证凭据
`PENPOT_SMTP_TLS` / `PENPOT_SMTP_SSL`	`false` / `false`	传输加密开关（587 用 TLS，465 用 SSL）

配套旗标 enable-smtp（默认已开）。接真实邮件服务商时改这组变量 + 把 host 指向服务商；测试邮箱收到的邮件通过 mailpit 的 Web 界面查看（默认编排映射到宿主 8025，本例改绑 127.0.0.1:8148）。mailpit 的消息只存内存、服务重建即丢，官方注释明确「Should be only used as a temporal solution」。

3.5 Valkey（通知与导出队列）

参数	默认值	说明
`PENPOT_REDIS_URI`	`redis://penpot-valkey/0`	Redis 协议连接串，backend 与 exporter 共用。承担 WebSocket 通知协调 + 导出任务状态
`VALKEY_EXTRA_FLAGS`（valkey 服务侧）	`--maxmemory 128mb --maxmemory-policy volatile-lfu`	内存上限与淘汰策略；官方注释「可以加大但通常没必要」

3.6 导出服务与 WASM 渲染池

exporter 服务级参数（官方编排注释原文，默认已注释掉）：

参数	默认值	说明
`PENPOT_EXPORTER_MAX_CONCURRENT_JOBS`	4	同时渲染的导出任务数
`PENPOT_EXPORTER_MAX_JOBS_PER_PROFILE`	2	单用户排队上限
`PENPOT_EXPORTER_QUEUE_MAX`	64	队列总长
`PENPOT_EXPORTER_JOB_TTL`	3600	任务状态保留秒数
`PENPOT_WASM_WORKER_POOL_MAX` / `MIN`	2 / 1	WASM 渲染工作池规模
`PENPOT_WASM_WORKER_IDLE_TIMEOUT`	300	空闲回收秒数
`PENPOT_WASM_WORKER_IMAGE_CACHE_SIZE`	134217728（128MB）	图像缓存字节上限

exporter 还有两个固定联动变量：PENPOT_INTERNAL_URI: http://penpot-frontend:8080（渲染页取自前端，实测导出时 exporter 确实请求了 frontend 的 render.html）与共享的 PENPOT_REDIS_URI。多用户高频导出的团队调大并发参数时，注意 exporter 常驻内存（实测 461MiB 空闲态）会随并发上涨。

3.7 HTTP 体积限制与 JVM

参数	默认值	说明
`PENPOT_HTTP_SERVER_MAX_BODY_SIZE`	367001600（350MB）	请求体上限，影响大文件导入
`PENPOT_HTTP_SERVER_MAX_MULTIPART_BODY_SIZE`	367001600	已废弃（编排内注释：改用上一项）
`JVM_OPTS`（backend）	官方未设	本例实测追加 `-Xms256m -Xmx512m` 限制后端堆；注意堆外内存仍在，后端总占用实测约 2.1GiB

四、功能旗标（PENPOT_FLAGS）全表

旗标写在 x-flags 锚点的 PENPOT_FLAGS 空格分隔串里，frontend/backend/exporter 共享。官方编排注释列出的全部旗标（2026-10-28 实查）：

旗标	方向	作用
`registration`	启用类	开放自助注册（默认开；实测注册接口可用）
`login-with-password`	启用类	邮箱密码登录
`email-verification` / `disable-email-verification`	反向	邮箱验证；默认关闭验证（官方默认 flags 含 `disable-email-verification`）
`secure-session-cookies` / `disable-secure-session-cookies`	反向	Cookie 安全位；官方默认关闭（HTTP 可用），上 HTTPS 后应移除 disable
`smtp` / `enable-smtp`	启用类	启用邮件发送（默认开）
`smtp-debug`	启用类	SMTP 调试
`demo-users`	启用类	演示账号
`log-emails` / `log-invitation-tokens`	启用类	把邮件内容/邀请 token 打进日志（测试用）
`login-with-github` / `login-with-gitlab` / `login-with-google`	启用类	对应 OAuth 登录（需配套 client id/secret 变量）
`login-with-oidc`	启用类	通用 OIDC/SSO（配套 `PENPOT_OIDC_*` 组）
`login-with-ldap`	启用类	LDAP（配套 `PENPOT_LDAP_*` 组）
`prepl-server` / `enable-prepl-server`	启用类	运维诊断 REPL（官方默认开）
`telemetry`	启用类	匿名遥测（配套 `PENPOT_TELEMETRY_ENABLED`，官方编排默认 `"true"` + `PENPOT_TELEMETRY_REFERER: compose`）
`webhooks`	启用类	Webhook 事件推送
`enable-mcp`	启用类	MCP 接口（2.18 默认编排已含，对应 `mcp` 服务与前端 `/mcp/*` 路由）
`enable-admin-console`	启用类	管理控制台（2.18 默认编排已含，前端 `/admin-console` 路由）
`enable-air-gapped-conf`	启用类	纯内网模式：停用对 GitHub（库/模板）与 Google Fonts 的外部拉取

官方编排注释里的安全警告原文：

WARNING: if you're exposing Penpot to the internet, you should remove the flags 'disable-secure-session-cookies' and 'disable-email-verification'

即公网暴露前：去掉 disable-secure-session-cookies（配合 TLS 反代）与 disable-email-verification（配合真实 SMTP），并考虑关闭 registration 改为邀请制。

OAuth/OIDC/LDAP 的配套变量组（PENPOT_GOOGLE_CLIENT_ID/SECRET、PENPOT_OIDC_BASE_URI/AUTH_URI/TOKEN_URI/USER_URI/JWKS_URI/CLIENT_ID/CLIENT_SECRET/SCOPES/NAME/EMAIL_ATTR/ROLES*、PENPOT_LDAP_HOST/PORT/SSL/STARTTLS/BASE_DN/BIND_DN/BIND_PASSWORD/USER_QUERY/ATTRS_* 等）均为「旗标开启后才生效」的成组配置，完整清单见官方配置文档；OIDC 回调地址固定为 https://<域名>/api/auth/oidc/callback。另有两个域名管控变量：PENPOT_EMAIL_DOMAIN_WHITELIST/BLACKLIST 与 PENPOT_REGISTRATION_DOMAIN_WHITELIST（注册邮箱域白名单，邀请制团队常用）。

五、参数变更与生效操作

标准变更流程（实测）：

cd /opt/penpot/deploy
vi .env            # 或 vi docker-compose.yaml
docker compose up -d   # 只重建受影响服务；锚点级改动会重建多服务
docker compose logs penpot-backend | grep "welcome to penpot"   # 核对新 flags

两条实测经验：

锚点共享变量（flags/URI/数据库）会触发多服务重建，页面会有约 1 分钟不可用；只改 backend/exporter 服务级变量则影响面小。
PENPOT_PUBLIC_URI 与 PENPOT_FLAGS 的组合要一起评审：先上 TLS 再去掉 disable-secure-session-cookies，顺序颠倒会导致 Cookie 写不进浏览器。

六、参考链接

官方配置文档（参数总表）：https://help.penpot.app/technical-guide/configuration/
官方 2.18.5 编排文件：https://github.com/penpot/penpot/blob/2.18.5/docker/images/docker-compose.yaml
站内系列：《Penpot 介绍与选型指南》 · 《Penpot Docker Compose 部署实战》 · 《Penpot 常用命令与运维实战》