Plane 配置参数详解

Plane v1.4.2 自托管配置体系详解：plane.env 全量变量分组表（端口/TLS、WEB_URL+CORS 联动、数据库/Redis/RabbitMQ 连接、SECRET_KEY、S3 凭证与 FILE_SIZE_LIMIT、限流、Webhook 白名单）、实例级数据库配置（God Mode 注册开关/SSO/SMTP 键与默认值源码核对）、配置修改生效规则与 SECRET_KEY 轮换实测（2026-10-27）。

PlanePlane项目管理PostgreSQL2026/10/27

Plane 配置参数详解

目标：把 Plane（makeplane/plane，官网 plane.so）社区版 v1.4.2 自托管实例的配置体系讲透——编排层 plane.env 全量变量、后端设置代码的读取点、实例级数据库配置（God Mode）三层各管什么、怎么改、何时生效。本文基于官方编排模板逐项核对 + 运行中实例的设置源码抽查（2026-10-27 实测环境：v1.4.2 Compose 部署，部署过程见《Plane Docker Compose 部署实战》）。

一、配置体系总览：三层结构

Plane 自托管实例的配置分三层，生效路径与修改方式各不相同：

层载体管什么修改方式生效时机
编排层plane.env（官方 variables.env 改名而来）端口、域名、密钥、依赖连接、副本数、TLS 证书编辑文件需 docker compose up -d 重建对应服务
应用层Django settings（读取环境变量）上述变量的运行时消费（CORS、上传上限、限流等）间接（随编排层）随服务重建
实例层数据库 InstanceConfiguration 表注册开关、SSO、SMTP、第三方 Key 等运营配置实例管理端（God Mode）或接口即时生效（带缓存失效机制）

三个要点（源码抽查证据，2026-10-27 于运行实例核对）：

  1. 实例层配置的默认值来自环境变量：实例配置注册表用 os.environ.get("ENABLE_SIGNUP", "0") 这类写法取 env 作初值，存库后以库内值为准（/code/plane/license/api/views/instance.py 第 60–130 行）。
  2. 实例层修改后即时生效：相关接口挂了 @invalidate_cache 装饰器（/code/plane/license/api/views/configuration.py 第 64 行）。
  3. 编排层改动必须重建服务才生效，且部分变量之间有联动约束（WEB_URL/CORS_ALLOWED_ORIGINS/端口必须一致，见第六章）。

二、plane.env 全量变量详解

以下为 v1.4.2 官方模板 variables.env（部署后为 plane.env）的全部变量，按功能分组。「实测值」列为本文部署实例的生效值（部署要点见《Plane Docker Compose 部署实战》4.2 节）。

2.1 全局与版本

变量实测值/默认说明
APP_RELEASEv1.4.2全部服务统一使用的版本标签，升级改这一处即可
APP_DOMAINlocalhost入口域名，TLS 证书签发与入口路由使用
DOCKERHUB_USERmakeplane镜像命名空间
PULL_POLICYif_not_present拉取策略（升级时官方建议改 always）
CUSTOM_BUILDfalse是否使用自定义构建
DOCKER_PLATFORM（注释，默认不启用）ARM64 上对应版本无镜像时取消注释并设 linux/amd64

2.2 副本数（编排 replicas 取值）

变量实测值说明
WEB_REPLICAS / SPACE_REPLICAS / ADMIN_REPLICAS1三个前端服务副本数
API_REPLICAS / WORKER_REPLICAS / BEAT_WORKER_REPLICAS1Django API 与 Celery 副本数（beat 固定单副本）
LIVE_REPLICAS1实时协作服务副本数

2.3 入口端口与 TLS 证书

变量实测值说明
LISTEN_HTTP_PORT8145（官方默认 80）入口 HTTP 监听端口（proxy 服务发布端口）
LISTEN_HTTPS_PORT8146（官方默认 443）入口 HTTPS 监听端口
CERT_ACME_CAhttps://acme-v02.api.letsencrypt.org/directoryACME CA 地址（默认 Let's Encrypt 生产环境）
CERT_EMAIL（空）签发证书的联系邮箱；要自动签证书就填
CERT_ACME_DNS（空）DNS-01 挑战配置，格式 acme_dns <DNS服务商> <API_KEY>（模板注释）
TRUSTED_PROXIES0.0.0.0/0信任的代理网段（在自有网关后面时收紧为实际网段更安全）
SITE_ADDRESS:80proxy 服务内部监听地址，一般不动

2.4 站点地址与跨域（联动强约束）

变量实测值说明
WEB_URLhttp://localhost:8145对外站点基准地址：邮件里的链接、跨域基准、分享链接都基于它；带端口要与 LISTEN_HTTP_PORT 一致
CORS_ALLOWED_ORIGINShttp://localhost:8145允许的跨域来源；设置代码按逗号/空白拆分为列表（settings/common.py 第 182–186 行实测核对），必须包含 WEB_URL 同源地址
DEBUG0调试模式开关，模板默认 0，生产保持 0
API_BASE_URLhttp://api:8000前端服务访问 API 的栈内地址（走内部网络，不需对外）

⚠️ 三个变量必须联动一致：LISTEN_HTTP_PORT、WEB_URL、CORS_ALLOWED_ORIGINS。实测若 WEB_URL 带了 8145 端口而 CORS 没带（或反之），页面能打开但登录/数据请求会因跨域失败。端口冲突改法与后果实测见《Plane Docker Compose 部署实战》第七章 Q2。

2.5 数据库（PostgreSQL）

变量实测值说明
PGHOST / PGDATABASEplane-db / plane业务库地址与库名（栈内服务名）
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DBplane / plane / plane建库三件套（POSTGRES_* 同时是 plane-db 服务初始化变量）
POSTGRES_PORT5432数据库端口
PGDATA/var/lib/postgresql/data数据目录（对应 pgdata 卷）
DATABASE_URL（空）整串连接串；接外部托管数据库时填它并注释掉栈内 plane-db（官方编排注释「Comment this if you already have」）

2.6 缓存/队列中间件（Redis 与 RabbitMQ）

变量实测值说明
REDIS_HOST / REDIS_PORTplane-redis / 6379缓存连接（v1.4.2 编排实际是 Valkey，Redis 协议兼容）
REDIS_URL（空）整串连接串，接外部 Redis 时使用
RABBITMQ_HOST / RABBITMQ_PORTplane-mq / 5672Celery 队列连接
RABBITMQ_USER / RABBITMQ_PASSWORD / RABBITMQ_VHOSTplane / plane / plane队列认证与虚拟主机
AMQP_URL（空）整串连接串，接外部 RabbitMQ 时使用

2.7 密钥（必须替换）

变量实测值说明
SECRET_KEY64 位 hex（模板默认 change-this-key-on-deployment）Django 会话签名/加密基准密钥；官方注释给出两种生成方式：python3 -c "from django.utils.crypto import get_random_secret_key; print(get_random_secret_key())" 或 openssl rand -hex 32。更换会使全部登录会话失效（实测见第六章）
LIVE_SERVER_SECRET_KEY64 位 hex（模板默认同上）实时协作（live）与后端的共享密钥，官方注释同样要求部署前替换、openssl rand -hex 32 生成

2.8 对象存储（S3/MinIO）

变量实测值说明
USE_MINIO11=使用编排内建 MinIO；0=接外部 S3（同时把 AWS_* 指向外部端点）
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEYaccess-key / secret-key对象存储凭证；USE_MINIO=1 时同时也是 MinIO 根凭证（两者必须一致）
AWS_S3_ENDPOINT_URLhttp://plane-minio:9000S3 端点；USE_MINIO=1 时为栈内地址
AWS_S3_BUCKET_NAMEuploads附件桶名
AWS_REGION（空）AWS S3 区域（接真实 AWS 时填）
FILE_SIZE_LIMIT5242880（默认同值）单附件上限（字节，默认 5 MB）；实测确认同时约束 DATA_UPLOAD_MAX_MEMORY_SIZE（settings/common.py 第 353、371 行核对）
MINIO_ENDPOINT_SSL0强制 HTTPS 语义开关（外部对象存储为 HTTPS 时按需设 1）

💡 附件实际上传链路（实测，详见部署篇 4.8 节）：客户端先经 /api/assets/v2/... 登记换预签名凭证，再直传入口域名的 /uploads 路径（proxy 转发到对象存储）。FILE_SIZE_LIMIT 参与预签名策略的 content-length-range 条件，因此声明 size 与实际字节数不一致会被 400 拒绝。

2.9 性能与限流

变量实测值说明
GUNICORN_WORKERS1（默认 2）API 服务 gunicorn 进程数；实测环境为资源占用设 1，生产建议按 CPU 调
API_KEY_RATE_LIMIT60/minute（默认同值）API Key 请求限流（settings/common.py 第 154 行核对）
AUTHENTICATION_RATE_LIMIT10/minute（默认同值）匿名认证接口（魔链生成/登录/注册、邮箱登录）按 IP 限流，DRF 格式 <n>/<period>（官方模板注释）

2.10 Webhook SSRF 防护白名单

变量实测值说明
WEBHOOK_ALLOWED_IPS（空）逗号分隔 IP/CIDR，允许作为 webhook 目标的私有网段（如 10.0.0.0/8,192.168.1.0/24）
WEBHOOK_ALLOWED_HOSTS（空）逗号分隔主机名，绕过私有 IP SSRF 校验（适合内网服务，官方示例 silo.namespace.svc.cluster.local）

三、实例级配置（数据库层 / God Mode）

实例层配置存在数据库 InstanceConfiguration 表，初值取自环境变量，之后可在实例管理端（God Mode，入口 /god-mode/）可视化修改，改后即时生效。v1.4.2 注册表全部键及默认值（2026-10-27 从运行实例源码 /code/plane/license/api/views/instance.py 逐项核对）：

3.1 注册与认证策略

键默认说明
ENABLE_SIGNUP0是否允许任意人自助注册
DISABLE_WORKSPACE_CREATION0禁止普通用户自建工作区
ENABLE_MAGIC_LINK_LOGIN1魔法链接登录开关
ENABLE_EMAIL_PASSWORD1邮箱密码登录开关

3.2 SSO/OAuth

键默认说明
IS_GOOGLE_ENABLED / IS_GITHUB_ENABLED / IS_GITLAB_ENABLED / IS_GITEA_ENABLED0四类第三方登录开关（客户端凭证同样经 God Mode 填写）
GITHUB_APP_NAME（空）GitHub App 名称
SLACK_CLIENT_ID（空）Slack 集成

3.3 SMTP 邮件（邀请/通知必配）

键默认说明
ENABLE_SMTP0SMTP 总开关
EMAIL_HOST / EMAIL_PORT（空）/（空）SMTP 服务器与端口
EMAIL_HOST_USER / EMAIL_HOST_PASSWORD（空）SMTP 认证
EMAIL_USE_TLS / EMAIL_USE_SSL—加密方式（值 1 为启用，二者互斥使用）
EMAIL_FROM（空）发件人地址

实例信息里 is_smtp_configured 直接取 bool(EMAIL_HOST)（configuration.py 第 159 行核对）；God Mode 提供「发送测试邮件」能力（对应 EmailCredentialCheckEndpoint，用上述凭证建立连接发样例邮件）；「停用邮件」端点会把 EMAIL_* 键清空、ENABLE_SMTP 置 0（configuration.py 第 72–79 行核对）。未配置 SMTP 的实例无法发出邀请邮件，新用户只能靠管理员在后台直接添加或开放自助注册。

3.4 第三方服务键

键默认说明
POSTHOG_API_KEY / POSTHOG_HOST（空）产品遥测（自托管可留空）
UNSPLASH_ACCESS_KEY（空）封面图库
LLM_API_KEY（空）AI 能力密钥

四、配置修改操作手册

改编排层（plane.env）：编辑 → 重建 → 验证三步。以改端口为例（实测命令）：

cd /opt/data/quzuo/tmp/plane/cli/plane-app
vi plane.env          # 改 LISTEN_HTTP_PORT / WEB_URL / CORS_ALLOWED_ORIGINS
docker compose -f docker-compose.yaml --env-file plane.env up -d
# 实测回显（重建 8 个服务后）：
#  Container plane-142-stack-admin-1  Recreated
#  Container plane-142-stack-admin-1  Started
#  ...（web/space/api/worker/beat-worker/live/proxy 同样 Recreated → Started）

重建范围由 Compose 按 env 依赖自动判定：改端口/域名/密钥会重建全部应用服务，改数据库连接则连 migrator 一起重建。

改实例层（God Mode）：浏览器进入 http://<地址>:8145/god-mode/，在 Authentication/Email 等页签修改后保存即生效；接口方式对应 /api/instances/（需实例管理员会话）。

五、实测：SECRET_KEY 轮换行为

在运行实例上做了完整的密钥轮换实验（2026-10-27，详见部署篇第七章 Q3）：

  1. 改前 /api/users/me/ 返回 200；
  2. plane.env 更换 SECRET_KEY 后 up -d 重建（实测 Recreated 8 个应用服务）；
  3. 旧会话 cookie 立即失效，/api/users/me/ 返回 401；
  4. 重新登录后恢复 200，业务数据（工作区/项目/Issue/附件）不受影响。

结论：SECRET_KEY 只影响会话与签名，不参与数据加密，轮换安全性好但要预期全员掉线；LIVE_SERVER_SECRET_KEY 同理影响实时协作连接。

六、常见问题（配置视角）

Q1：能用 q1w2e3r4 之类的演示密码吗？ 不能。密码策略是产品内置（Django 校验器 + zxcvbn 熵值 ≥3），不是环境变量可关闭项，实测 q1w2e3r4 被拒（This password is too common.）。详见部署篇 4.6 节。

Q2：接外部 S3 的最小变量集？ USE_MINIO=0 + 外部 AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_S3_ENDPOINT_URL/AWS_S3_BUCKET_NAME（AWS Region 按需），并在编排文件注释掉 plane-minio 服务（官方编排注释原话「Comment this if you already have an S3-compatible storage」）。同理外部数据库填 DATABASE_URL、外部 Redis 填 REDIS_URL、外部队列填 AMQP_URL。

Q3：改了 env 但没生效？ 编排层变量必须 docker compose up -d 重建；Compose 按 env 内容变化自动判断重建哪些服务，只改了 plane.env 不重建是无效的。实例层配置（God Mode）才是即时生效。

Q4：FILE_SIZE_LIMIT 调大后仍传不了大文件？ 检查三点：该变量同时约束 DATA_UPLOAD_MAX_MEMORY_SIZE（需重建 api/worker）；代理层若另有 client_max_body_size 限制需同步；预签名直传声明 size 必须与实际字节一致（实测差 1 字节即 400 EntityTooLarge）。

Q5：官方文档里说的 SMTP/OAuth 配置在 plane.env 里找不到？ v1.4.2 的运营类配置（SMTP、SSO、遥测键）默认值走实例配置注册表（os.environ.get("EMAIL_HOST", "") 等），既可在 plane.env 预置，也可部署后在 God Mode 填写，存库生效。编排模板里没有这些键属正常。

七、参考链接