Plane 自托管部署与本地开发实战：从 Docker Compose 编排到 Monorepo 开发环境-平芜编程栈

Plane 自托管部署与本地开发实战：从 Docker Compose 编排到 Monorepo 开发环境

【免费下载链接】plane🔥🔥🔥 Open-source Jira, Linear, Monday, and ClickUp alternative. Plane is a modern project management platform to manage tasks, sprints, docs, and triage.项目地址: https://gitcode.com/GitHub_Trending/pl/plane

本文以 Plane 仓库根目录的 README.md 为核心，系统讲解这款开源项目管理平台（可替代 Jira、Linear、Monday、ClickUp）的能力边界、自托管部署拓扑、环境变量配置以及完整的本地开发工作流。读完本文，你将能够：根据 docker-compose.yml 复现 Plane 的全部容器化部署链路，理解 web / api / worker / live 等各服务的职责分工，并按照 CONTRIBUTING.md 的规范在本地跑起完整的开发环境并参与贡献。

一、Plane 是什么：定位与核心功能

Plane 的自我定位是"为所有团队提供现代化的项目管理"（Modern project management for all teams），一个用于跟踪 issues、运行 cycles、管理产品路线图（roadmaps）的开源工具。README 将产品功能归纳为六大模块：

Work Items：基于功能完备的富文本编辑器创建和管理任务，支持文件上传、子属性（sub-properties）以及关联 issue 引用；
Cycles：以迭代周期维持团队节奏，配合 burn-down 等图表追踪进度；
Modules：把复杂项目拆分为更小、更易管理的模块；
Views：通过自定义过滤器只显示最相关的 issue，并可保存、共享视图；
Pages：带 AI 能力的富文本知识库，支持格式化、插图、超链接，以及把笔记转换为可执行事项；
Analytics：跨所有 Plane 数据的实时洞察，可视化趋势、定位并移除阻塞项。

这些功能在代码层面分别对应仓库中的前端组件与后端模型。例如，前端工作项视图组件位于 apps/web/core/components，编辑器作为独立包 packages/editor 存在，后端模型层（180 个 Python 文件）集中在 apps/api/plane/db。

二、两条使用路径：Cloud 与自托管

README 将安装方式分为两条路径：

Plane Cloud：直接在官方云服务注册，免去基础设施运维，是最快的上手方式；
Self-host Plane：在自有服务器上安装运行，获得对数据和基础设施的完全控制权。

官方自托管支持两种主流方式，README 中以徽章链接到开发者文档：

安装方式	说明
Docker	通过 docker-compose 编排部署，对应仓库根目录的 docker-compose.yml
Kubernetes	提供 deployments/kubernetes/community 目录及说明文档

除根目录的 compose 文件外，仓库还提供了多套部署变体，覆盖不同场景：

docker-compose-local.yml：本地开发环境，将apps/api源码以 volume 挂载进容器实现热重载；
docker-compose-test.yml：测试环境；
deployments/aio/community/Dockerfile 与 supervisor.conf：All-in-One 单容器社区版部署；
deployments/cli/community/docker-compose.yml 与 install.sh：CLI 一键安装方式。

此外 README 指出：实例管理员（Instance admins）可以通过God mode配置实例设置。这与仓库中独立的apps/admin前端应用一致——在本地开发中，你需要先访问http://localhost:3001/god-mode/注册为实例管理员（该路径对应apps/api/.env.example中的ADMIN_BASE_PATH="/god-mode"）。

三、Monorepo 架构：前端、后端与共享包

Plane 是一个 monorepo，README 的 "Built with" 部分标注了核心技术栈：React Router（前端路由框架）、Django（后端）、Node.js（运行时）。从仓库结构看，apps/目录下的五个应用分别承载不同职责：

应用	目录	职责
主 Web 前端	apps/web	面向最终用户的产品界面（issue、cycle、module、view 等），151 个页面级 tsx 文件
Admin 控制台	apps/admin	God mode 实例管理台，实例初始化、认证提供方（GitHub/GitLab/Google/Gitea）配置
Space 应用	apps/space	独立空间视图，含 issue 详情、编辑器组件
API 后端	apps/api	Django 项目，含`authentication`、`space`、`app`等模块与 Celery 后台任务
Live 协同服务	apps/live	基于 Yjs/Hocuspocus 的实时协同服务（WebSocket），使用 Redis

packages/目录沉淀了跨应用共享的包：packages/constants（全局常量）、packages/editor（Tiptap 富文本编辑器）、packages/i18n（国际化，18 种语言）、packages/services（API 服务层）、packages/types（类型定义）、packages/ui 与 packages/propel（UI 组件库）等。工程配置上，仓库使用 pnpm workspace（pnpm-workspace.yaml）加 Turborepo（turbo.json）组织多包构建。

四、生产部署拓扑：docker-compose.yml 逐项解析

docker-compose.yml 定义了完整的生产级部署，共 11 个服务。逐个说明：

应用层服务

web：构建自 apps/web/Dockerfile.web，主前端，依赖api；
admin：构建自 apps/admin/Dockerfile.admin，管理台，依赖api和web；
space：构建自 apps/space/Dockerfile.space，依赖api和web；
api：构建自 apps/api/Dockerfile.api，入口脚本为./bin/docker-entrypoint-api.sh，环境变量来自 apps/api/.env，依赖数据库与 Redis；
worker：与api同镜像，入口docker-entrypoint-worker.sh，运行 Celery worker 处理后台任务（issue 自动化、导出、webhook、邮件通知等，任务定义见 apps/api/plane/bgtasks）；
beat-worker：Celery Beat 定时任务调度器，入口docker-entrypoint-beat.sh；
migrator：一次性迁移容器（restart: no），执行docker-entrypoint-migrator.sh完成数据库迁移；
live：构建自 apps/live/Dockerfile.live，实时协同服务；
proxy：构建自 apps/proxy/Dockerfile.ce，唯一的端口暴露服务（${LISTEN_HTTP_PORT}:80、${LISTEN_HTTPS_PORT}:443），承担反向代理与 SSL 终结。compose 文件明确注释："如果你已经运行着一个反向代理，可以注释掉该服务"。代理层还消费FILE_SIZE_LIMIT（默认 5242880 字节，约 5 MB）与BUCKET_NAME（uploads）两个变量。

基础设施服务

服务	镜像	关键点
`plane-db`	`postgres:15.7-alpine`	`max_connections=1000`，数据卷`pgdata`，凭据来自`.env`的`POSTGRES_USER/DB/PASSWORD`
`plane-redis`	`valkey/valkey:7.2.11-alpine`	以 Valkey（Redis 兼容实现）承载缓存与队列，数据卷`redisdata`
`plane-mq`	`rabbitmq:3.13.6-management-alpine`	消息队列，使用`RABBITMQ_USER/PASSWORD/VHOST`，挂载管理界面
`plane-minio`	`minio/minio`	S3 兼容对象存储，`server /export --console-address ":9090"`，根账号映射自`AWS_ACCESS_KEY_ID/SECRET_ACCESS_KEY`

四个命名卷（pgdata、redisdata、uploads、rabbitmq_data）分别承载持久化数据。值得注意的是：虽然 CONTRIBUTING.md 将 Postgres v14、Redis v6.2.7 列为最低版本要求，但当前仓库 compose 文件实际固定为 Postgres 15.7 与 Valkey 7.2.11，自托管时以 compose 文件为准。

五、环境变量配置：.env.example 全解

setup.sh会把所有.env.example复制为.env（根目录及apps/{web,api,space,admin,live}六处），因此理解各 example 文件是正确配置的关键。

根目录 .env：基础设施与存储

.env.example 的关键项：

数据库：POSTGRES_USER="plane"、POSTGRES_PASSWORD="plane"、POSTGRES_DB="plane"、PGDATA；
Redis：REDIS_HOST="plane-redis"、REDIS_PORT="6379"；
RabbitMQ：RABBITMQ_HOST/PORT/USER/PASSWORD/VHOST（默认用户与密码均为plane，vhost 为plane）；
监听端口：LISTEN_HTTP_PORT=80、LISTEN_HTTPS_PORT=443（映射到 proxy 服务）；
S3/MinIO：AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_S3_ENDPOINT_URL="http://plane-minio:9000"、AWS_S3_BUCKET_NAME="uploads"（注释提示：修改桶名后若使用 minio 需同步修改代理配置）、FILE_SIZE_LIMIT=5242880（最大上传体积）；
USE_MINIO=1：使用预配置的 MinIO 时置 1；
SSL：CERT_ACME_CA（Let's Encrypt 端点）、CERT_EMAIL（设置后自动生成证书）、CERT_ACME_DNS（DNS 挑战方式）、TRUSTED_PROXIES、MINIO_ENDPOINT_SSL=0（强制 HTTPS 开关）；
API_KEY_RATE_LIMIT="60/minute"：API 密钥速率限制。

API 配置：apps/api/.env

apps/api/.env.example 面向 Django 后端：

DEBUG=0（注释明确：生产环境使用 0）、CORS_ALLOWED_ORIGINS（默认放行 localhost 的 3000/3001/3002/3100 四个前端端口）；
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}：由上面变量拼装，POSTGRES_HOST="plane-db"即 compose 服务名；
GUNICORN_WORKERS=2：API 工作进程数；
SIGNED_URL_EXPIRATION=3600：文件签名 URL 有效期（秒），注释给出 30 / 300 的示例取值；
HARD_DELETE_AFTER_DAYS=60：文件硬删除周期；
各前端基础地址：APP_BASE_URL="http://localhost:3000"、ADMIN_BASE_URL="http://localhost:3001"+ADMIN_BASE_PATH="/god-mode"、SPACE_BASE_URL="http://localhost:3002"+SPACE_BASE_PATH="/spaces"、LIVE_BASE_URL="http://localhost:3100"+LIVE_BASE_PATH="/live"；
LIVE_SERVER_SECRET_KEY：与 live 服务共享的密钥，两侧必须一致。

Django 侧的设置加载机制见 apps/api/plane/settings：local.py用于本地/开发（compose-local 中 migrator 显式使用--settings=plane.settings.local），production.py、test.py分别对应生产与测试，redis.py、storage.py等拆分了 Redis 与对象存储配置。

前端配置：VITE 变量

apps/web/.env.example（space、admin 的 example 与之相同）统一通过 VITE 前缀注入构建期变量：VITE_API_BASE_URL（API 地址）、VITE_WEB_BASE_URL、VITE_ADMIN_BASE_URL+VITE_ADMIN_BASE_PATH、VITE_SPACE_BASE_URL+VITE_SPACE_BASE_PATH、VITE_LIVE_BASE_URL+VITE_LIVE_BASE_PATH。apps/live/.env.example 则包含PORT=3100、API_BASE_URL、LIVE_SERVER_SECRET_KEY及 Redis 连接（REDIS_HOST/PORT/URL，注释说明若不提供完整 Redis URL 可用 HOST+PORT 替代）。

六、本地开发全流程：setup.sh 到 god-mode

README 的 "Local development" 一节直接指向 CONTRIBUTING.md，其开发环境要求如下：

Docker Engine 已安装并运行；
Node.js 20+（LTS）；
Python 3.8+；
Postgres v14（当前 compose 实际使用 15.7）；
Redis v6.2.7（当前 compose 实际使用 Valkey 7.2.11）；
内存：建议至少 12 GB RAM——CONTRIBUTING 明确警告：8 GB 内存的机器在容器构建、启动或依赖安装阶段可能导致 setup 失败或内存崩溃，建议使用云开发环境或升级内存。

完整步骤（来自 CONTRIBUTING "Projects setup and Architecture" 章节）：

克隆仓库（monorepo 中后端 Django 项目在apps/api）：

git clone https://gitcode.com/GitHub_Trending/pl/plane [folder-name] cd [folder-name] chmod +x setup.sh

运行 setup.sh。脚本做的事比表面多：它将根目录与apps/{web,api,space,admin,live}六份.env.example复制为.env；随后用tr -dc 'a-z0-9' < /dev/urandom | head -c50随机生成 50 位 DjangoSECRET_KEY并追加到apps/api/.env；再执行corepack enable pnpm激活 pnpm 并安装 Node 依赖。脚本结尾提示下一步：docker compose -f docker-compose-local.yml up -d。
启动容器：
```
docker compose -f docker-compose-local.yml up
```
docker-compose-local.yml 与生产版的差异：基础设施镜像版本一致（Postgres 15.7 / Valkey 7.2.11 / RabbitMQ 3.13.6 / MinIO），但api、worker、beat-worker、migrator使用 apps/api/Dockerfile.dev 构建，并通过 volume 把./apps/api挂载到容器内/code实现热重载；plane-db、plane-redis、plane-minio额外暴露了 5432 / 6379 / 9000 / 9090 端口便于本地调试；MinIO 的 entrypoint 还内嵌了mc客户端自动创建uploads桶；所有服务加入共享的dev_envbridge 网络。
启动 Web 应用：
```
pnpm dev
```
由根目录 package.json 经 Turborepo 并行驱动各前端应用的 dev server，分别监听 3000（web）、3001（admin）、3002（space）、3100（live）。
注册实例管理员：打开http://localhost:3001/god-mode/，注册自己为 instance admin。
登录主应用：打开http://localhost:3000，用第 5 步的相同凭据登录。

CONTRIBUTING 还附带了调试提示：若改动没有自动刷新，请手动刷新浏览器。

编码规范方面，CONTRIBUTING 要求所有功能或修复必须附带至少一个单元测试（spec），并使用 OxLint（共享.oxlintrc.json）做 lint、oxfmt（.oxfmtrc.json）做格式化。API 后端测试运行方式见 apps/api/RUNNING_TESTS.md。

七、贡献、安全与社区

README 的贡献与治理章节给出了明确的参与路径：

提 Issue 规范（来自 CONTRIBUTING.md）：提 bug 前先在 issues 中搜索；须提供最小可复现场景，说明所用第三方库版本及失败用例；标题采用固定格式——🐛 Bug: [描述]、🚀 Feature: [描述]、🛠️ Improvement: [描述]、📘 Docs: [描述]；
贡献方式：试用 Plane Cloud 与自托管平台并反馈、添加新集成、补充或更新翻译、处理 open issues、撰写教程与博文、提交 feature 提案、报告 bug、完善文档；
国际化贡献：CONTRIBUTING 单独详述了翻译结构——语言文件位于 packages/i18n/src/locales，嵌套 JSON 键结构，使用 IntlMessageFormat 处理变量与复数（ICU 格式），新增语言需同步更新TLanguage类型（packages/i18n/src/types/language.ts）、SUPPORTED_LANGUAGES常量与语言文件导入逻辑；
安全：发现漏洞应负责任地私下披露而非公开 issue，邮件 security@plane.so，详见 SECURITY.md；
社区：官方通过 GitHub Discussions 与论坛运营社区，遵循 CODE_OF_CONDUCT.md；
许可：项目采用 GNU Affero General Public License v3.0（LICENSE.txt）。

八、小结

Plane 的仓库组织为"一个 monorepo、五个应用、十一个容器服务"的清晰分层：apps/web、apps/admin、apps/space、apps/live四个 Node 前端/协同应用围绕 Django 后端apps/api构建，再由proxy统一对外。自托管的核心是理解 docker-compose.yml 中api → worker / beat-worker / migrator的 Celery 分工、Postgres/Valkey/RabbitMQ/MinIO 四个基础组件，以及根目录.env与apps/api/.env中数据库、存储、SSO 相关变量的联动关系；本地开发则只需./setup.sh→docker compose -f docker-compose-local.yml up→pnpm dev三步，再从:3001/god-mode注册实例管理员即可进入贡献流程。