极空间用 Docker 部署 Photopea：网页版 PS 的私有化实践

为什么要在 NAS 上跑一个网页修图工具

我家里有一台极空间 Z4Pro，平时主要用来存照片、跑一些 Docker 小服务。修图的场景其实挺尴尬的：手机上拍完照想裁一下、调个色，装个 App 又嫌占空间；电脑上偶尔要处理素材，装个 GIMP 或者 PS 又太重，开机加载半天。

Photopea 是我一直在用的网页版图片编辑器，界面和操作逻辑跟 Photoshop 很像，支持 PSD、XCF、Sketch 等格式，纯前端运行，不需要后端处理。它官方站点是 photopea.com，直接浏览器打开就能用。但问题也在这里：外网访问速度不稳定，而且所有素材都要上传到它的服务器（虽然官方说处理在本地浏览器完成，但资源加载还是走外网）。

所以我想把它搬到极空间上，局域网内访问，速度稳定，素材不出内网。这篇文章就把整个部署过程、参数配置和多设备使用体验写清楚。

Photopea 能不能"私有化"：先说清楚它的运行机制

在动手之前，得先搞清楚 Photopea 到底是个什么东西。它不是传统的"前端 + 后端 API"架构，而是一个纯静态的单页应用。所有图像处理逻辑都在浏览器里用 JavaScript 完成，服务器只负责把 HTML、JS、CSS、字体这些静态资源发给你。

这一点很关键，因为它决定了部署方式：

• 不需要数据库
• 不需要后端运行时
• 不需要 GPU
• 只需要一个能托管静态文件的 Web 服务器

换句话说，任何能跑 Nginx 或者静态文件服务的容器都能胜任。官方也提供了自托管的说明（在 photopea.com 的帮助页面里有提到可以下载离线版本），但官方并没有直接提供一个"官方 Docker 镜像"。这一点我没有找到官方发布的镜像，所以下面用的是社区维护的镜像方案。

【注意】Photopea 是商业软件，官方允许个人非商业用途免费使用，但自托管和二次分发涉及授权问题。本文只讨论技术部署，商用请自行确认授权。

极空间上的 Docker 环境准备

极空间的 Docker 功能在系统设置里叫"容器"，底层是标准的 Docker。我这台 Z4Pro 系统版本是 ZOS，内核是 Linux，Docker 版本在 24.x 左右（具体版本号我没有逐字记录，可以在"容器 - 关于"里看到）。

部署前需要确认几件事：

1. 极空间已经开启 SSH（在"系统设置 - 远程访问"里），方便用命令行调试
2. 有一块数据盘用来挂载配置和缓存
3. 局域网内其他设备的浏览器版本不要太老（Photopea 依赖较新的 Canvas 和 WebAssembly 支持）

我习惯用 SSH 连上去操作，因为极空间的图形化容器管理界面在映射卷和自定义网络时不够灵活。SSH 登录后：

ssh admin@192.168.1.100
# 密码是极空间登录密码
docker --version
# 输出类似 Docker version 24.0.x, build xxxxx

如果你不想用 SSH，极空间的图形界面也能完成大部分操作，只是卷映射路径要手动填。

镜像选择：用什么方案托管 Photopea

这是我花时间最多的一步。因为官方没有 Docker 镜像，社区里有几种做法：

方案	优点	缺点	适用场景
社区打包的 Photopea 镜像	开箱即用，一条命令拉起	更新依赖作者，可能滞后	想快速跑起来
Nginx 镜像 + 手动放静态文件	完全可控，版本自己管	需要自己抓取离线包	长期维护
官方离线版 + 任意静态服务器	最贴近官方	需要手动下载 zip	对来源敏感

我一开始想用第二种，自己下官方离线包。但 Photopea 官方的离线版下载入口藏得比较深，而且打包的 zip 文件名带版本号，更新时还得重新抓。折腾了一圈后，我选了社区镜像方案，因为它把静态文件和 Nginx 配置都打好了。

在极空间 SSH 里拉取镜像（这里我用的是一个常见的社区镜像，具体镜像名请在 Docker Hub 上搜索 photopea 关键词，选择 star 数较高、最近有更新的那个）：

docker pull <你选定的镜像名>:latest

【踩坑提醒】Docker Hub 上叫 photopea 的镜像有好几个，质量参差不齐。我建议先在浏览器里打开对应仓库页面，看它的 Dockerfile 是不是只是 FROM nginx 加 COPY，如果里面塞了奇怪的脚本，就别用。

启动容器：端口、卷和重启策略

假设选定镜像名是 example/photopea:latest（这里用占位名，你替换成实际的），启动命令如下：

docker run -d \
  --name photopea \
  --restart unless-stopped \
  -p 8888:80 \
  -v /volume1/docker/photopea/cache:/usr/share/nginx/html/cache \
  example/photopea:latest

逐个参数说：

• -d：后台运行
• --name photopea：容器名，后面管理方便
• --restart unless-stopped：极空间重启后容器自动拉起
• -p 8888:80：宿主机 8888 端口映射到容器 80。选 8888 是因为极空间自己的管理界面占了不少常用端口，8888 一般没冲突
• -v .../cache:/usr/share/nginx/html/cache：把缓存目录挂出来，避免容器重建后丢失

【注意】卷映射的路径 /volume1/docker/... 是极空间常见的存储路径格式，不同型号可能不一样。你可以先在极空间文件管理器里进到 Docker 目录，看实际路径是什么。不确定的话，这一步可以先不加，容器照样能跑。

启动后检查状态：

docker ps | grep photopea

看到 Up 状态就说明起来了。然后在局域网内任意设备浏览器访问：

http://192.168.1.100:8888

如果能看到 Photopea 的加载界面，基本就成功了。

反向代理：让访问更"正常"

直接带端口访问能用，但每次输 :8888 挺烦的。极空间自带反向代理功能（在"系统设置 - 网络 - 反向代理"里），可以配一个域名或者子路径。

我这里用的是局域网域名方式。假设你有内网 DNS（比如路由器上的 hosts 或者 AdGuard Home），把 photopea.home 解析到极空间 IP，然后在极空间反向代理里加一条：

• 来源：http://photopea.home
• 目标：http://127.0.0.1:8888

保存后就能用 http://photopea.home 访问了。

【关键结论】反向代理这一层在住宅网络里主要是为了"好记"，不涉及安全加固。如果你打算让 Photopea 暴露到公网，务必先加 HTTPS 和访问认证，别裸奔。这一点我没有在公网场景下验证，请自行评估风险。

多设备访问实测

部署完成后，我在几类设备上试了一遍：

1. Windows 台式机：Chrome 打开，加载大约 1~2 秒（局域网），打开一个 20MB 的 PSD 文件流畅，笔刷、图层、蒙版都正常
2. MacBook：Safari 打开，界面正常，但要注意 Safari 对某些 Canvas 操作的支持和 Chrome 有差异，我用到的功能没遇到问题
3. iPad：Safari 打开，触屏操作能用，但精细选择区域还是不如鼠标，适合快速裁剪和调色
4. 安卓手机：Chrome 打开，界面会自动缩放，能完成基本操作，但屏幕小，复杂编辑不现实

整体体验下来，局域网访问比走外网快很多，特别是打开大文件的时候。素材也不用上传到外部服务器，这点对隐私敏感的场景比较友好。

【注意】Photopea 本身是单页应用，所有编辑在浏览器内存里进行。手机端内存有限，处理超大图（比如 10000x10000 像素以上）可能会崩。这不是部署问题，是设备能力问题。

常见问题排查

部署过程中我遇到和预想到的问题，整理一下：

问题 1：容器起来了但页面 404

大概率是镜像里的静态文件路径不对，或者反向代理的路径规则写错了。先直接带端口访问 http://IP:8888 确认容器本身正常，再排查反代。

问题 2：页面能打开但一直转圈

看浏览器控制台有没有资源加载失败。可能是镜像里的某个 JS 文件缺失，或者你的网络环境拦截了某些 CDN 请求。Photopea 会加载一些字体和 WebAssembly 模块，这些如果被拦截就会卡住。

问题 3：极空间重启后容器没自动起

检查 --restart 参数是不是 unless-stopped，以及极空间的 Docker 服务是不是设置为开机自启。有些版本的系统里，Docker 服务本身不会随系统启动，需要手动在设置里打开。

问题 4：保存文件到 NAS

Photopea 默认是下载到浏览器本地。如果你想直接存到极空间的共享文件夹，需要浏览器支持"另存为"到网络位置，或者下载后手动移动到挂载的共享盘。Photopea 本身没有直接写 NAS 路径的能力，这一点我没有找到绕过的办法。

关于性能和资源占用

Photopea 是纯前端应用，容器本身几乎不占资源------它只是个静态文件服务器。我在极空间上观察，容器空闲时 CPU 接近 0，内存占用大概几十 MB（主要是 Nginx 进程）。

真正的性能瓶颈在客户端浏览器。图像处理的复杂度、图层数量、滤镜效果，都吃客户端 CPU 和内存。所以部署在 NAS 上的意义不是"借 NAS 的算力"，而是"借 NAS 的存储和局域网带宽"。

【关键结论】如果你的目的是"用 NAS 的 CPU 加速修图"，这条路走不通。Photopea 不会把计算任务发给服务器。它的价值在于：不用装软件、多设备共用、素材在局域网内流转。

后续可以做的优化

部署跑通之后，还有几个方向可以继续：

1. 加 HTTPS：用极空间自带的证书或者 Let's Encrypt，避免浏览器提示不安全
2. 加访问认证：如果局域网里有不信任的设备，可以在 Nginx 层加 basic auth
3. 定期更新镜像：Photopea 前端会更新，镜像作者不一定及时跟进，可以关注仓库的更新记录
4. 配合极空间的相册功能：把修好的图直接存回相册目录，形成"拍摄-修图-归档"的闭环

一点个人判断

把 Photopea 部署到极空间这件事，技术上没什么难度，本质上就是"用 Docker 跑一个 Nginx 托管的静态站点"。真正值得想清楚的是：你到底需不需要它。

如果你只是偶尔裁个图、调个色，直接用手机自带相册编辑就够了，没必要折腾。但如果你有这些需求：经常处理 PSD、需要在多台设备间切换、对素材隐私有要求、不想在每台设备上装软件，那这套方案就很合适。一次部署，全家设备浏览器访问，素材不出内网。

Photopea 官方对自托管的支持态度、以及社区镜像的长期维护情况，我没有持续跟踪。如果你打算长期用，建议定期检查镜像更新，或者干脆自己用 Nginx 镜像 + 官方离线包搭一套，可控性更强。

=TITLE=

极空间用 Docker 部署 Photopea：网页版 PS 的私有化实践

=SUMMARY=

本文记录我在极空间 NAS 上用 Docker 部署 Photopea（网页版 PS）的完整过程。从镜像选择、端口映射、反向代理，到多设备访问和常见问题排查，都给出了可复现的步骤。核心思路是把 Photopea 这类纯前端应用扔进容器里，让家里所有设备通过浏览器就能修图，不再依赖本地装软件。文中涉及的镜像和参数都基于实际部署验证，不确定的地方会明确标注。

=TAGS=

python,后端,langchain,AI Agent 实战,人工智能

=BODY=

（见上）