1. 为什么选择Docker部署Penpot？一个设计师的亲身经历

几年前，我还在一个创业团队里负责产品设计。那时候，团队的设计协作简直是场灾难。设计师用Figma，产品经理用Axure，开发同学又习惯在代码里直接写注释，文件传来传去，版本混乱不堪，一个按钮的颜色改了三次，最后上线时还是错的。后来我们尝试过一些在线的设计协作工具，但要么是费用太高，小团队负担不起，要么就是对数据安全有顾虑，毕竟有些设计稿涉及核心产品思路。

直到我发现了Penpot。说实话，最开始是被“开源”和“免费”这两个词吸引的。这意味着我可以把它部署在我们自己的服务器上，所有设计数据都掌握在自己手里，这对于很多对数据敏感的企业和团队来说，是个巨大的吸引力。但当时一看官方的手动安装文档，头就大了：需要分别配置PostgreSQL数据库、Redis缓存、后端服务、前端服务，还有一堆环境变量，光是想想就觉得麻烦，更别提后续的维护和升级了。

就在我快要放弃的时候，我看到了Docker Compose的部署方式。Docker对我来说并不陌生，用它部署过不少开发环境，但用它来部署一个如此复杂的、生产级的设计协作平台，一开始心里还是有点打鼓。但实际操作下来，我发现这简直是“柳暗花明又一村”。Docker把Penpot这个由多个微服务组成的复杂应用，打包成了几个简单的容器，我们只需要一个配置文件、几条命令，就能让整个系统跑起来。这就像以前组装电脑需要自己买CPU、主板、内存、硬盘，一个个安装调试；而现在Docker给了我们一台品牌整机，插上电就能用。

所以，如果你也面临以下这些情况，那么用Docker搭一个自己的Penpot，绝对是个值得尝试的方案：你的团队需要一个专属的、安全的设计协作空间，不想把数据放在第三方云端；你们预算有限，但又不愿牺牲协作体验；或者你和我一样，是个喜欢把技术掌控在自己手里的“折腾派”。接下来，我就把我踩过坑、验证过的完整部署流程分享给你，保证你跟着做，半小时内就能拥有一个功能强大的私有化设计平台。

2. 部署前的准备工作：给Penpot一个舒适的家

在开始“盖房子”（部署Penpot）之前，我们得先准备好“地基”和“工具”。这一步看似简单，但准备充分能避免后面很多莫名其妙的错误。我刚开始就曾因为系统资源不足，导致服务启动一半卡住，排查了半天。

2.1 硬件与系统环境检查

首先，你得有一台服务器。它可以是云服务商提供的云主机（比如1核2G配置的就能跑起来），也可以是你公司内网的一台性能不错的电脑，甚至是家里的NAS（如果它支持Docker的话）。我这里以最常用的Ubuntu 22.04 LTS系统为例，其他Linux发行版（如CentOS、Debian）的命令会略有不同，但思路完全一致。

关键点一：资源评估。 Penpot的各个组件（前端、后端、数据库、Redis）对资源有一定要求。根据我的经验，如果只是小团队（10人以内）轻度使用，1核CPU、2GB内存、20GB硬盘的服务器勉强够用。但为了运行流畅，我强烈推荐至少2核CPU、4GB内存。内存尤其重要，因为PostgreSQL和Redis都是内存消耗大户。你可以用 free -h 命令查看当前内存，用 df -h 命令查看磁盘空间，确保至少有10GB的可用空间。

关键点二：网络与防火墙。 Penpot前端默认使用9001端口。你需要确保服务器的防火墙（如ufw或firewalld）开放了这个端口，或者如果你在云平台，需要在安全组规则里放行TCP 9001端口。你可以用 sudo ufw allow 9001/tcp（如果使用UFW）来快速开放。同时，也要确保服务器能正常访问外网，因为我们需要从Docker Hub拉取镜像。

2.2 安装Docker与Docker Compose

这是核心步骤。Docker现在安装已经非常方便了，但我们要安装的是官方源的最新稳定版，而不是系统自带的可能过时的版本。

打开你的服务器终端，依次执行以下命令。这些命令的作用是添加Docker的官方APT仓库，安装必要的工具，然后安装Docker引擎和Compose插件。

# 1. 更新现有的软件包列表，确保我们基于最新的信息安装
sudo apt update

# 2. 安装一些允许apt通过HTTPS使用仓库的依赖包
sudo apt install -y ca-certificates curl gnupg lsb-release

# 3. 添加Docker的官方GPG密钥（用于验证软件包签名）
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 4. 设置Docker的稳定版仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. 再次更新APT包索引，这次会包含新添加的Docker仓库
sudo apt update

# 6. 安装Docker引擎、命令行工具、containerd运行时以及Docker Compose插件
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

安装完成后，我们需要做两件重要的事：一是将当前用户加入docker用户组，这样以后运行docker命令就不需要每次都加sudo了；二是启动Docker服务并设置开机自启。

# 将当前用户添加到docker组（记得将`your_username`替换成你的实际用户名）
sudo usermod -aG docker your_username

# 启动Docker服务
sudo systemctl start docker

# 设置Docker服务开机自动启动
sudo systemctl enable docker

重要提示：执行完usermod命令后，你需要完全退出当前终端会话，然后重新登录，或者新开一个终端窗口，用户组的变更才会生效。之后，你就可以直接运行 docker version 和 docker compose version 来验证安装是否成功了。如果能看到版本号信息而没有权限错误，说明一切就绪。

3. 一键获取与配置：让Penpot按你的想法运行

环境准备好了，现在该请出主角Penpot了。Penpot团队非常贴心，为我们准备好了一个“开箱即用”的Docker Compose配置文件。这个文件就像一份详细的“施工图纸”，定义了Penpot需要哪些“房间”（容器）、每个房间怎么布置（环境变量）、以及房间之间如何连通（网络）。

3.1 下载官方Docker Compose配置

我们有两种方式获取这个文件。第一种是直接用curl命令下载到当前目录。我更喜欢用这种方式，简单直接。

# 使用curl命令从Penpot的GitHub仓库拉取最新的docker-compose.yaml文件
curl -o docker-compose.yaml https://raw.githubusercontent.com/penpot/penpot/main/docker/images/docker-compose.yaml

如果你服务器上没有安装curl，也可以使用wget命令，效果是一样的：wget https://raw.githubusercontent.com/penpot/penpot/main/docker/images/docker-compose.yaml。下载完成后，用 ls -la 命令检查一下，应该能看到一个名为 docker-compose.yaml 的文件。

3.2 深度解读与关键配置修改

现在，别急着启动。我们先花几分钟看看这个配置文件，理解一下它都干了什么，并根据我们的需求做一些关键调整。用 nano docker-compose.yaml 或 vim docker-compose.yaml 打开它。

你会看到文件里定义了好几个services，这就是Penpot的各个微服务组件：

• penpot-frontend：前端界面，我们最终在浏览器里访问的就是它。
• penpot-backend：后端API，处理所有业务逻辑。
• penpot-exporter：指标导出器，用于监控。
• penpot-postgres：PostgreSQL数据库，存放用户、团队、文件等所有核心数据。
• penpot-redis：Redis缓存，用于实时协作的WebSocket通知等。
• penpot-mailcatch：一个临时的邮件捕获服务，用于开发和测试环境查看发出的邮件。

第一个必改项：访问地址。 在文件靠前的位置，你会找到 x-uri 这个锚点定义：

x-uri: &penpot-public-uri
  PENPOT_PUBLIC_URI: http://localhost:9001

这里的 localhost:9001 意味着服务启动后，只能通过服务器本机访问。如果你希望从其他电脑（比如你的工作机）通过服务器的IP地址来访问，就必须修改它。例如，你的服务器内网IP是 192.168.1.100，那么就改成：

  PENPOT_PUBLIC_URI: http://192.168.1.100:9001

如果你有域名，并打算配置HTTPS，这里可以填 https://your-domain.com。注意：这个变量非常重要，后端服务生成的各种链接（如重置密码链接）都基于此，填错了会导致功能异常。

第二个关键项：安全相关标志。 在 x-flags 部分，官方配置为了简化初始体验，默认禁用了一些安全特性：

PENPOT_FLAGS: disable-email-verification enable-smtp enable-prepl-server disable-secure-session-cookies

• disable-secure-session-cookies：禁用了安全会话Cookie。这意味着Cookie在非HTTPS连接下也会被传输，不安全。如果你只是在纯内网环境测试，可以暂时不管。但如果你计划通过公网IP或域名访问，务必在配置好HTTPS后，移除这个标志。
• disable-email-verification：禁用了邮件验证。因为初始配置用的是临时的mailcatch服务，无法真正发送验证邮件。对于正式使用，当你配置了真实的SMTP邮箱服务（比如公司邮箱或SendGrid等第三方服务）后，也应该移除这个标志，启用邮件验证。

第三个建议项：修改默认密码。 在 penpot-postgres 服务部分，你会看到环境变量设置了默认的数据库用户名和密码（都是penpot）。从安全角度，你应该修改它们：

environment:
  - POSTGRES_DB=penpot
  - POSTGRES_USER=your_strong_username  # 修改这里
  - POSTGRES_PASSWORD=your_strong_password  # 修改这里

同时，别忘了在 penpot-backend 服务的环境变量里，同步修改 PENPOT_DATABASE_USERNAME 和 PENPOT_DATABASE_PASSWORD 的值，让后端能连上数据库。

4. 启动与验证：见证Penpot诞生的时刻

配置都调整好了，最激动人心的启动环节来了。这个过程非常简单，但我们需要理解命令背后的含义。

4.1 使用Docker Compose启动所有服务

确保你的终端当前目录就在 docker-compose.yaml 文件所在的文件夹下，然后运行这条“魔法”命令：

sudo docker compose up -d

分解一下这个命令：

• docker compose：调用Docker Compose工具（我们安装的是插件版，所以是compose而不是旧的docker-compose）。
• up：创建并启动配置文件中定义的所有服务。
• -d：代表“detached”，让服务在后台运行。如果不加这个参数，所有容器的日志都会打印在当前终端，退出终端服务就停了。

执行命令后，你会看到Docker开始从网络拉取（Pull）各个服务的镜像（Image）。第一次运行会花费一些时间，取决于你的网速。镜像拉取完毕后，Docker会基于镜像创建容器（Container），并按照配置的依赖关系（depends_on）依次启动它们。

你可以随时使用 sudo docker compose logs -f 命令来实时查看所有容器的日志输出，-f 参数表示持续跟踪。观察日志，直到看到后端和前端服务启动成功的提示，没有明显的错误信息。

4.2 访问平台与初始化账号

当所有服务都启动完成后，打开你的浏览器，在地址栏输入你之前配置的访问地址，比如 http://你的服务器IP:9001。如果一切顺利，你将看到Penpot的欢迎界面。

第一次访问，你需要创建一个管理员账号。点击注册，输入你的邮箱、用户名和密码。这里注册的第一个账号会自动成为整个实例的管理员，拥有最高权限，可以创建团队、管理成员等，所以请务必使用一个你牢记的邮箱和密码。

注册成功后，系统可能会提示你去邮箱验证。因为我们用的是内置的mailcatch服务，所以并没有真的发邮件出去。要查看这封“虚拟”的验证邮件，你可以访问 http://你的服务器IP:1080。这是一个邮件管理界面，所有由Penpot系统“发出”的邮件都会在这里显示，你可以直接点击邮件中的验证链接来完成验证流程。这个设计对于调试和初始设置非常方便。

登录进去后，你就进入了Penpot的主界面。可以先创建一个团队（Team），然后邀请其他成员（通过他们的邮箱）。被邀请的成员会收到邀请邮件（同样可以在mailcatch里看到），点击链接即可加入你的团队，开始协作设计之旅。

5. 进阶配置与生产环境调优

如果你只是想在内部测试玩玩，那么到上一步就已经完成了。但如果你想把它用于团队日常协作，甚至对外提供服务，以下几个进阶配置能让你用得更踏实、更高效。

5.1 配置真实的SMTP邮件服务

Mailcatch只是个临时方案，它不能真的发邮件。要让Penpot的注册验证、密码重置、邀请通知等功能真正生效，你必须配置一个真实的SMTP服务。

你需要准备以下信息：SMTP服务器地址（如smtp.gmail.com）、端口（如587）、用户名（通常是你的邮箱地址）、密码（可能是邮箱密码或应用专用密码）。然后，回到 docker-compose.yaml 文件，找到 penpot-backend 服务的环境变量部分，修改SMTP相关配置：

# 启用SMTP功能（确保PENPOT_FLAGS里有enable-smtp）
# 配置真实的SMTP信息
PENPOT_SMTP_DEFAULT_FROM: your-email@your-domain.com  # 发件人地址
PENPOT_SMTP_DEFAULT_REPLY_TO: your-email@your-domain.com # 回复地址
PENPOT_SMTP_HOST: smtp.your-email-provider.com  # SMTP服务器主机
PENPOT_SMTP_PORT: 587  # 端口，通常是587（TLS）或465（SSL）
PENPOT_SMTP_USERNAME: your-email@your-domain.com  # 登录用户名
PENPOT_SMTP_PASSWORD: your-email-password-or-app-specific-password  # 登录密码
PENPOT_SMTP_TLS: true  # 是否启用TLS，根据服务商要求设置
PENPOT_SMTP_SSL: false # 是否启用SSL，通常与TLS二选一

重要安全提醒：不建议将邮箱密码明文写在配置文件里。更安全的做法是使用Docker的密钥管理功能，或者通过环境变量文件（.env）来传递，并在版本控制中忽略这个文件。配置完成后，重启服务：sudo docker compose down 然后 sudo docker compose up -d。重启后，尝试注册一个新用户或邀请成员，看看是否能收到真实的邮件。

5.2 启用HTTPS与配置域名

通过HTTP访问不仅不安全，而且很多浏览器新特性（如某些PWA功能）会受限。为你的Penpot实例配置HTTPS是生产环境的必备步骤。有几种常见方式：

方式一：使用反向代理（推荐）。这是最灵活、最通用的方式。你可以在Penpot前面部署一个Nginx或Traefik作为反向代理，由它们来处理HTTPS证书（比如用Let‘s Encrypt自动申请和续签），然后将HTTP请求转发给后端的Penpot服务。这样，Penpot本身的配置几乎不用改动。你需要做的是：1. 安装并配置Nginx/Traefik，申请SSL证书。2. 修改Nginx配置，将对你域名的HTTPS请求代理到 http://服务器本地IP:9001。3. 将 docker-compose.yaml 中的 PENPOT_PUBLIC_URI 改为 https://your-domain.com。4. 务必从 PENPOT_FLAGS 中移除 disable-secure-session-cookies，以启用安全Cookie。

方式二：使用Docker Compose文件中的Traefik示例。官方配置里其实已经给出了一个注释掉的 traefik 服务示例。如果你熟悉Traefik，可以取消注释那部分配置，并填写你的邮箱和域名，Traefik会自动帮你完成HTTPS证书的申请和配置。这种方式更“Docker化”，但需要对Traefik有一定的了解。

5.3 数据持久化与备份

Docker Compose配置中已经使用了“命名卷”（volumes）来持久化PostgreSQL数据库和上传的素材资源。这意味着即使你删除并重新创建容器，数据也不会丢失。这些卷默认存储在Docker的管理目录下（通常是/var/lib/docker/volumes/）。

但为了更安全，你应该定期备份这些数据。最简单的方法是使用 docker compose exec 命令来执行数据库备份：

# 进入postgres容器，执行pg_dump备份命令，将备份文件输出到容器内
# 然后从容器内复制到宿主机
sudo docker compose exec penpot-postgres pg_dump -U penpot penpot > /path/on/your/host/penpot_backup_$(date +%Y%m%d).sql

请将 /path/on/your/host/ 替换为你服务器上的一个实际备份目录。你还可以将备份命令写成脚本，结合crontab实现自动定时备份。

对于存储设计文件的 penpot_assets 卷，你可以直接找到对应的物理目录进行打包备份。使用 sudo docker volume inspect penpot_assets 命令可以查看该卷在宿主机上的具体挂载路径。

5.4 版本升级与日常维护

Penpot团队会定期发布新版本，修复Bug并增加新功能。升级你的Docker版Penpot非常简单，基本是“无痛”的。

1. 拉取新镜像：首先，修改 docker-compose.yaml 文件顶部的 PENPOT_VERSION 环境变量（如果没有，可以添加），或者直接使用 latest 标签（不推荐用于生产环境，因为可能包含不稳定的变更）。更稳妥的做法是指定一个具体的版本号，如 PENPOT_VERSION: 2.0。
2. 停止并更新服务：在配置文件所在目录，运行 sudo docker compose down。这会停止并移除当前的所有容器，但不会删除你的数据卷。然后运行 sudo docker compose pull 来拉取指定版本的新镜像。
3. 重新启动：运行 sudo docker compose up -d。Docker会基于新的镜像创建新的容器，并挂载原有的数据卷，你的所有数据和设置都会保留。

日常维护中，你可以使用 sudo docker compose ps 查看服务状态，使用 sudo docker compose logs [服务名] 查看特定服务的日志。如果某个服务异常，可以尝试 sudo docker compose restart [服务名] 来重启它。

我自己的Penpot实例已经稳定运行了大半年，期间升级过两次版本，过程都非常顺利。这种基于容器的部署方式，把复杂的运维工作简化到了极致，让我可以更专注于使用工具本身去创造价值，而不是整天折腾环境。希望这份详细的指南也能帮你快速搭建起属于自己团队的设计协作中心，让创意和协作变得更加流畅。