Plane 如何用 setup.sh 完成自托管首次安装并配置 plane.env 后启动服务-平芜编程栈

Plane 如何用 setup.sh 完成自托管首次安装并配置 plane.env 后启动服务

【免费下载链接】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

这篇文章解决一个明确任务：在一台装有 Docker 的机器上，用 Plane 官方的setup.sh完成自托管首次安装，把plane.env中访问相关的变量配置好，然后启动整套服务并确认实例可用。全文基于仓库中的自托管文档 Self Hosting 指南，脚本行为以仓库内的 install.sh 为准，环境变量模板对应 variables.env。适用对象是 Docker Compose 单节点部署（Docker Swarm 是另一条路径，文末说明边界）。

准备条件：Docker、系统与权限

README 列出的前置要求：

Docker 已安装并处于运行状态。装完后在终端执行docker --version能显示版本号即安装成功；
操作系统支持 bash 脚本（Ubuntu、Linux AMI、macOS）。Windows 系统需要先安装 gitbash；
当前用户必须能访问 Docker 服务，多数情况下用sudo su切换到 root 用户后再执行后续步骤；
后续所有步骤都在终端（Windows 下为 gitbash）窗口中执行。

环境分两种来源：

云服务器：文档以 AWS EC2 为例，实例最低要求 2 vCPU、4GB RAM。在该机器上执行下面的命令安装 Docker Engine——该命令会从 get.docker.com 下载并在系统上安装 Docker，需要具有足够权限的用户执行：
```
curl -fsSL https://get.docker.com | sh -
```
本地桌面：从 Docker Hub 下载 Docker Desktop（Mac 或 Windows 版本），按安装向导完成安装并打开 Docker Desktop。Windows 安装时可能被要求启用 Hyper-V 和 Containers 功能，并注销或重启使变更生效。

关于 CPU 架构：setup.sh会自动检测架构（x86_64/amd64归为 amd64，aarch64/arm64归为 arm64），并检查所选 release 是否存在当前架构的预制镜像。如果当前架构没有预制镜像，脚本会询问是否改为本地构建镜像（会 clone 仓库代码并执行docker compose build --no-cache，属于较重的构建操作）。variables.env中另有一条注释：ARM64 环境且当前APP_RELEASE没有对应镜像时，可以取消注释DOCKER_PLATFORM=linux/amd64。

下载 setup.sh

mkdir plane-selfhost cd plane-selfhost curl -fsSL -o setup.sh https://github.com/makeplane/plane/releases/latest/download/setup.sh chmod +x setup.sh

该命令从 Plane 的 latest release 下载setup.sh并赋予执行权限。如果走 Docker Swarm 部署方式，README 给出的是同一位置的swarm.sh（保存为setup.sh），其菜单与本文不同；本文只覆盖 Docker Compose 方式。

首次安装：生成 plane-app 目录与 plane.env

在终端运行./setup.sh，会出现动作菜单（README 中的示例；当前仓库install.sh中第一项显示为1) Install）：

Select an Action you want to perform: 1) Install (x86_64) 2) Start 3) Stop 4) Restart 5) Upgrade 6) View Logs 7) Backup Data 8) Exit Action [2]: 1

首次安装输入1。安装过程中脚本会依次：检查最新 release 版本、校验当前架构的镜像可用性、把最新的docker-compose.yaml和plane.env（由variables.env模板生成，旧环境文件会先备份为plane.env.bak并归档到plane-app/archive/）下载到plane-app目录，并拉取所有镜像。

安装完成后菜单会再次弹出，这次输入8退出。

安装成功的判断：当前目录下生成了plane-app文件夹，其中包含docker-compose.yaml和plane.env两个文件。

配置 plane.env

用任意文本编辑器打开plane-app/plane.env。README 指出必须重点确认的键：

键	默认值	说明
`LISTEN_HTTP_PORT`	`80`	所选端口不能被占用，例如改为`LISTEN_HTTP_PORT=8080`
`WEB_URL`	`http://localhost`	改为实际使用的 FQDN 或 IP 加上端口，例如`https://plane.example.com:8080`或`http://[IP-ADDRESS]:8080`
`CORS_ALLOWED_ORIGINS`	`http://localhost`	改为与`WEB_URL`相同的域名

模板文件中WEB_URL和CORS_ALLOWED_ORIGINS由APP_DOMAIN派生（默认APP_DOMAIN=localhost），修改访问地址时注意保持一致。

README 还建议配置EMAIL SETTINGS（邮箱设置），开启后才能邀请团队成员加入平台。

面向生产环境的提示来自variables.env的注释：SECRET_KEY与LIVE_SERVER_SECRET_KEY的默认值都标注为“部署到生产前必须修改”，并给出了生成方式——openssl rand -hex 32（或 Django 的随机密钥命令python3 -c "from django.utils.crypto import get_random_secret_key; print(get_random_secret_key())"）。

如果之后还要改动plane.env，README 建议先停掉服务再修改（停止方式见下文）。

启动服务

再次运行./setup.sh，这次选择2（Start）：

Select a Action you want to perform: 1) Install (x86_64) 2) Start 3) Stop 4) Restart 5) Upgrade 6) View Logs 7) Backup Data 8) Exit Action [2]: 2

启动过程中会下载镜像，耗时取决于下载速度和机器配置。install.sh的start流程按如下顺序收尾：等待 migrator 容器完成数据库迁移（退出码非 0 会判定启动失败），然后对 API 容器做健康检查（在容器内请求http://localhost:8000/，最长等待 5 分钟），全部通过后输出（以下为脚本内置的输出文案，不是固定日志格式）：

Data Migration completed successfully ✅ API Service started successfully ✅ Plane Server started successfully ✅ You can access the application at $WEB_URL

最后两行会打印你在plane.env中配置的$WEB_URL实际值。看到这段输出后，浏览器访问你配置的地址（例如http://[IP-ADDRESS]:8080）即可打开 Plane 实例。

验证启动结果

浏览器验证：用配置好的 URL 访问，README 将其作为“自托管成功”的确认方式（文档配有一张服务全部 running 的截图images/started.png作为参考画面）。

日志验证：运行./setup.sh选择6（View Logs），会进入服务子菜单，可选 Web、Space、API、Worker、Beat-Worker、Migrator、Proxy、Redis、Postgres、Minio、RabbitMQ，0返回主菜单。例如选3查看 API 日志，CTRL+C退出。README 给出的 API 日志示例（文档示例，实际时间戳与环境变量不同）：

api-1 | Waiting for database... api-1 | Database available! api-1 | No migrations Pending. Starting processes ... api-1 | [INFO] Starting gunicorn 21.2.0 api-1 | [INFO] Listening at: http://0.0.0.0:8000 (1) api-1 | [INFO] Application startup complete.

启动失败的判断信号（均来自install.sh的实际输出逻辑）：

migrator 退出码非 0：输出Plane Server failed to start ❌，提示检查 migrator 服务日志，并给出停止命令./setup.sh stop；
找不到 API 容器：Error: API container not found. Please check if services are running.；
API 5 分钟健康检查超时：输出API Service did not respond to health-check – please verify manually.，需要手动检查；
安装阶段拉镜像失败：Failed to pull the images. Exiting...，此时脚本已回滚之前归档的 compose 文件。

限制与后续操作

修改plane.env后，README 的做法是先停服务（./setup.sh选3，或直接./setup.sh stop），改完再启动；不需要停机、只想重启时选4（Restart）。
版本升级不是首次安装的一部分，但文档将其列为日常维护：./setup.sh选5（Upgrade）会停掉服务并重新下载最新的docker-compose.yaml和plane.env，完成后必须人工核对plane.env中的新增变量，再回到 Start 步骤。
数据备份用菜单7（Backup Data），会打包 pgdata、uploads、redisdata 等卷到plane-app/backup/下的时间戳目录；Swarm 部署没有这套 Compose 菜单，需按其自身流程处理。