Docker 部署在线 PPT 工具 PPTist：内网自托管与 Nginx 配置全流程

把在线 PPT 工具跑在自己的服务器上这件事，我第一次做的时候纯粹是被逼的。
那时团队每个迭代都要给客户做方案演示，材料涉及不少商业细节，不能传到公有网盘，微信传来传去两天就能整出三四个版本。后来我在一台闲置服务器上把 PPTist 部署起来，用 Docker 构建成镜像，内网同事打开固定地址就能新建演示文稿、编辑、放映，敏感资料全程不落第三方。这篇东西就是这个部署过程的完整记录，包括镜像构建的取舍、Nginx 侧的处理、公网访问的安全控制，以及后来真实踩过的几个坑。适合手里有云服务器或内网机器、想搭建一个私有在线演示环境的人参考，哪怕你以前没怎么用过 Docker，按顺序操作也能跑通。

1. PPTist 到底能解决什么，又解决不了什么

1.1 一个浏览器就能用的开源演示编辑器

PPTist 本质上是一个运行在浏览器里的演示文稿编辑器，界面和交互方式跟大家熟悉的 PPT 软件很像。它不依赖 Office 环境，也不需要每台电脑装客户端，打开网页就能新建幻灯片、插入文本、形状、图片、图表、表格、音视频，也能做基础的动画和切换效果，还支持演讲者备注。对“团队内部需要快速做汇报材料、方案展示、培训课件”这类场景来说，它的轻量程度非常合适。

因为项目本身是 Vue 3 + TypeScript 写的，编译完就是一堆静态文件，所以部署形态很灵活。你可以扔到任意 Web 服务器上，也可以用 Docker 打成一个镜像，跑在任何能运行容器的主机上。这一点非常契合自托管的需求——没有平台绑定、没有账号体系限制，只要内网能访问，就能一直用下去。

1.2 自托管最大的价值：数据边界

很多人问，网上现成的在线 PPT 编辑器那么多，为什么还要自托管？答案很简单：数据边界。

公司内部的方案、价格策略、客户名单、产品路线图，这些东西放在第三方在线文档服务上，即使对方说加密存储，你也很难完全放心。尤其是一些拿了保密合同的项目，客户对数据流向有明确要求，内部材料不允许落到外部服务器。PPTist 自托管后，所有页面资源、用户操作数据都只存在于你自己的服务器和访问者浏览器里，不经过任何第三方链路。对于内网环境，甚至可以把服务器完全断外网，照样能编辑、能放映。

另一个价值是稳定性。公有在线工具哪天服务变更、访问受限，你的演示环境就跟着不可用。自托管实例没有这个问题，Docker 镜像打好了，什么时候需要什么时候拉起来。

1.3 认清局限，部署完才不会骂娘

PPTist 不是什么都能干。它对“重度 PPT 用户”来说，动画能力、母版灵活性、插件生态，都不如桌面版 PowerPoint 完整。它更适合做内容直接、视觉干净的技术分享、方案宣传、课程课件，而不是花里胡哨的发布会级演示。

更要命的一点是：PPTist 默认并不是一个传统意义上的“平台”。它是纯前端应用，没有自带用户系统、没有云端文件服务器、没有多人协同编辑。数据默认落在浏览器本地，或者通过导出工程文件来保留。这一点我在下一章单独展开，因为部署前如果没搞清楚，后面你会觉得功能像“消失”了一样，到处找自己保存的 PPT。

这块认知比 Docker 命令本身更重要。部署一个工具只是开始，搞清楚工具的使用边界，才能把它放到正确的工作流里。

2. 部署前的关键判断：纯前端应用怎么理解“平台”两个字

2.1 默认数据存哪：决定你的工作流

我第一次部署完 PPTist 后，兴冲冲拿手机开了一个新演示文稿，编辑完退出，再打开发现里面是空的。当时第一反应是“服务坏了”，后来仔细翻了文档才明白：PPTist 这种纯前端形态，编辑内容默认保存在当前浏览器环境里。你自己电脑上编辑的内容，换一台电脑打开同一地址，并不会自动同步过去。

这意味着如果你希望团队“每个人打开地址都能看到同一份 PPT 文件”，需要一个配套方案。最常见也最简单的做法是：把 PPTist 当作本地制作工具，做完之后把工程文件导出，放到团队共享网盘或 NAS 上。需要继续编辑的人先下载，再拖进 PPTist 页面里打开。

所以严格说，PPTist 自托管后更像一个“统一版本的在线制作客户端”，而不是带用户中心的云文档系统。如果你需要多人协作编辑同一份演示文稿、在线评论、集中存储这些能力，需要自己做扩展，或者另选带后端的解决方案。

这个边界建议在推广给团队之前先说清楚，否则大家按照使用在线协作文档的习惯来用，会频繁发生“我做的 PPT 哪去了”的抱怨。

2.2 资源与运行清单

PPTist 构建产物是纯前端静态文件，运行时没有数据库、没有后端进程，资源占用极低。以我实际部署的经验，1 核 1G 的小机器跑它绰绰有余，内存占用大概只有几十 MB 到一两百 MB。真正吃资源的是浏览器端渲染和页面切换，但这部分跑在访问者自己设备上，和服务器无关。

部署前需要准备的东西很简单：

如果你在 Windows 上用 Docker Desktop，也可以跑这套流程，只是后续我会提醒几个 Windows 环境特有的坑。

另外，构建阶段需要访问 npm 仓库下载前端依赖。如果目标服务器是完全离线、没有外网的，需要提前在联网机器上把镜像打好，再迁移过去。这个方法我放到最后一章。

3. 从源码到可用镜像：一份可落地的 Dockerfile

3.1 为什么第一步是写镜像而不是拉现成镜像

很多软件自托管都有官方 Docker 镜像，拉下来就能用。但 PPTist 这个项目我翻了一圈，没有官方的现成镜像，以当前社区习惯来看，官方主要的交付方式是源码。那就自己写 Dockerfile 建镜像，顺便也可以针对自己的需求改前端代码。

写镜像没有想象中复杂。PPTist 的构建流程本质上就三步：
安装前端依赖 → 执行构建命令 → 把生成的静态文件丢给 Web 服务器。

比较推荐的方案是多阶段构建。第一个阶段用 Node.js 镜像做编译环境，第二个阶段用 Nginx 镜像做运行环境，最终镜像里只保留编译后的静态文件和轻量 Web 服务器。好处是镜像小、没有 node_modules 垃圾、运行环境干净。

3.2 一份可以直接用的 Dockerfile 和 .dockerignore

先拉取源码：

bash复制git clone https://github.com/pipipi-pikachu/PPTist.git
cd PPTist

在项目根目录创建 Dockerfile：

dockerfile复制# 第一阶段：构建前端资源
# 用 Node 20 而不是 latest，避免未来 Node 大版本升级带来的兼容性问题
FROM node:20-alpine AS build

WORKDIR /app

# 先复制 package.json 和 lock 文件，充分利用 Docker 层缓存
COPY package*.json ./

# 国内服务器强烈建议设置 npm 镜像，否则 install 能卡到你怀疑人生
ENV NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

RUN npm install

# 再复制整个项目源码并构建
COPY . .
RUN npm run build

# 第二阶段：运行静态资源
FROM nginx:1.25-alpine

COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

如果你拉取的仓库里有 package-lock.json，可以把 npm install 换成 npm ci。npm ci 严格按照 lock 文件安装依赖，构建可复现性更强，速度也往往会快一些。

在项目根目录创建 .dockerignore，这一步很多人会漏掉：

code复制node_modules
dist
.git
.gitignore
Dockerfile
docker-compose.yml
README.md
*.md

如果不忽略 node_modules，Docker 构建时会把本地依赖一起打包进构建上下文，不仅镜像体积暴增，构建速度也会变得极慢。想象一下把一个装满东西的房间原封不动搬进新家，再在新家里把不需要的物件一件件扔出去，纯属浪费体力。

3.3 npm 依赖安装慢与构建缓存处理

国内服务器构建前端项目时，最容易遇到的问题就是 npm install 卡住。如果你在主目录没有配 npm 全局源，Dockerfile 里那一行 ENV NPM_CONFIG_REGISTRY 就是兜底方案。如果不想把镜像源写死在 Dockerfile 里，也可以在宿主机上执行：

bash复制docker build --build-arg NPM_REGISTRY=https://registry.npmmirror.com -t pptist:latest .

但需要先修改 Dockerfile 用 ARG 接收这个参数。为了减少新手踩坑，我倾向于直接用 ENV 方式，简单直接。

还有一个容易忽略的点：Docker 层缓存。

COPY package*.json ./ 和 RUN npm install 放在前面，是为了让 Docker 在 package.json 没变化时直接复用 npm install 那一层缓存。如果你把 COPY . . 放在最前面，那么任何源码变更都会导致后面的依赖安装全部重跑，每次构建都要等几分钟。这点对后期频繁调整样式和逻辑非常关键。

第一次构建通常会花几分钟，后续只要不修改 package.json，基本几十秒就能出镜像。

4. docker compose 编排与 Nginx 配置的隐藏细节

4.1 编排文件怎么写最省心

构建镜像可以只用 docker build，但真要跑起来并且长期维护，建议用 docker compose 管理。项目根目录创建 docker-compose.yml：

yaml复制services:
  pptist:
    build:
      context: .
      dockerfile: Dockerfile
    image: pptist:latest
    container_name: pptist
    restart: unless-stopped
    ports:
      - "8080:80"
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1/"]
      interval: 30s
      timeout: 3s
      retries: 3

这个配置有几个隐藏好处：
restart: unless-stopped 保证服务器重启或容器异常退出时，服务能自动拉起来。
healthcheck 定期探活，配合 docker compose ps 能看到容器健康状态，而不是等用户反馈才知道服务挂了。
宿主机映射到 8080 而不是直接占 80，给后面加反向代理留出空间。

启动命令：

bash复制docker compose up -d --build

查看状态：

bash复制docker compose ps

看到 STATUS 一列是 healthy 或 Up，就说明容器正常。

4.2 Nginx 配置不只是把静态文件吐出去

在项目根目录创建 nginx.conf：

nginx复制server {
    listen 80;
    server_name _;

    root /usr/share/nginx/html;
    index index.html;

    client_max_body_size 100m;

    gzip on;
    gzip_min_length 1k;
    gzip_comp_level 6;
    gzip_types text/plain text/css application/json application/javascript application/xml image/svg+xml;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

这里要重点说的是 try_files $uri $uri/ /index.html;。Vue 这类前端项目在启用 history 路由时，如果直接访问一个子路由，比如 /edit/123，服务器上并没有这个物理文件，Nginx 会返回 404。加上这行后，找不到对应文件时自动回退到 index.html，由前端路由接管页面渲染。PPTist 如果后续你改了路由方式、做了内部跳转，这行能避免大量刷新白屏问题。

gzip 配置也值得提一下。Vue 打包后的 JS 文件通常不小，开启 gzip 后传输体积能减少一大半。在带宽比较紧张的内网或公网服务器上，这个配置直接决定页面首屏加载是 1 秒还是 5 秒。

client_max_body_size 默认只有 1m，如果你后面要接入素材上传、图片入库之类的能力，不调大这个值会遇到 413 Request Entity Too Large 错误。现在提前设成 100m，算是一个保险。

4.3 第一次启动后的功能验证

部署完不要急着拿给团队用，先用命令确认服务确实能正常响应：

bash复制curl -I http://127.0.0.1:8080

如果返回 HTTP/1.1 200 OK 和 text/html 类型的响应，基本没问题。浏览器打开：

code复制http://你的服务器IP:8080

能看到 PPTist 的编辑器界面，新建一页幻灯片随便加点内容，确认工具栏能正常弹出、字号颜色能改、能进入播放模式。再做一次导出操作，把当前工程文件下载到你本地。

我每次部署完都会执行三个动作：新开无痕窗口访问、导出一次工程文件、重新导入一次。无痕窗口能排除本地缓存干扰，导入导出则验证了最核心的数据链路没问题。这三步都过了再交付给别人使用，通常都比较稳。

5. 让服务可用且不乱入：反向代理、域名与基础认证

5.1 一句话说清为什么不要直接暴露 8080

如果你只是内网自己玩，没人访问也就无所谓。但一旦把 8080 端口映射到公网，就意味着全世界任何人都能访问你的编辑器界面。它没有登录功能，谁拿到地址都能新建、编辑、导出，相当于把你的内部服务裸奔在公网上。扫描器全天候扫全网端口，用不了几个小时就会被发现，然后被人拿来当免费作图工具还算小事，更糟的是可能被大量恶意请求拖垮服务，甚至被用于违规内容传播。

所以正式开放访问前，我会在容器前面再挂一层反向代理，对外只暴露 80/443 端口，同时加基础认证，只有知道账号密码的团队同事能打开。

5.2 Caddy 方案，自动 HTTPS 加 Basic Auth

如果手里有一个域名，我最推荐 Caddy，配置极短，并且自动申请和续期 HTTPS 证书。

先创建一个 Caddyfile：

caddyfile复制ppt.example.com {
    encode zstd gzip

    reverse_proxy 127.0.0.1:8080

    basic_auth {
        # 先用 caddy hash-password --plaintext '你的强口令' 生成哈希替换下面这一行
        viewer $2a$14$XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    }
}

然后启动 Caddy 容器或直接用宿主机 Caddy 进程。访问 https://ppt.example.com 时会弹出用户名密码框，通过后才能进入 PPTist 界面。

这时候数据链路是这样的：访问者浏览器与 Caddy 之间走 HTTPS 加密，Caddy 再把请求转发给本机 8080 端口上的 PPTist 容器。PPTist 容器只监听本机回环地址映射的 8080，不对公网直接开放，安全性和部署整洁度都更好。

Caddy 生成密码哈希的命令：

bash复制caddy hash-password --plaintext '改成你自己的强口令'

用户名我习惯用一个像 viewer 这样的普通词，不要用 admin、root。

5.3 已有 Nginx 时的反代写法

如果你服务器上已经跑了 Nginx，不想再引入 Caddy，直接用系统 Nginx 做反代也一样。在 nginx 配置里加一个 server 块：

nginx复制server {
    listen 80;
    server_name ppt.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

HTTPS 证书可以交给 certbot 自动申请，也可以沿用你已有的证书体系。区别只在于证书怎么弄，反向代理逻辑是一样的。

如果你不想用域名，公网 IP 访问也能配合基础认证使用，直接在 Nginx 里写 auth_basic 配置，或者干脆只把容器端口绑定到云防火墙的白名单网段里。自托管工具能小范围用起来和能大规模推广，完全是两个工程，先把访问入口收住是最基本的底线。

6. 实际跑起来之后的排障清单

6.1 先从容器状态说起

部署完最常见的现象是：docker compose up 之后浏览器打不开。这时候先别看业务逻辑，一上来就用 docker logs 看容器输出，这是最直接的办法。

bash复制docker compose ps
docker logs pptist --tail 100

如果容器状态是 Exited，说明进程启动失败，日志里通常会有 Nginx 配置错误或端口绑定失败的提示。
如果状态是 Restarting，大概率是健康检查不过或者 Nginx 进程反复崩溃。
如果是 Up 但访问不了，再检查端口映射和防火墙。

我遇到过几次容器正常但无法访问的情况，都是宿主机防火墙没有放行对应端口。云服务器尤其要注意安全组规则，Linux 本机防火墙也可能拦截。先用 curl http://127.0.0.1:8080 试本机，通了说明容器没问题，再看防火墙和安全组。

6.2 白屏、资源 404 与浏览器兼容

页面能打开但白屏，属于前端部署典型问题。处理步骤按顺序来：

先按 F12 打开开发者工具，切到 Network 面板，刷新页面看有没有红色 404 请求。如果有静态资源 404，说明构建产物没放对位置或路径不对。进入容器确认一下：

bash复制docker exec -it pptist sh
ls /usr/share/nginx/html
cat /usr/share/nginx/html/index.html

能看到 index.html 且引用资源路径存在，多数情况下是浏览器缓存了旧版本。强制刷新（Ctrl+Shift+R）一般能解决。如果控制台直接报 JavaScript 语法错误，可能是浏览器版本太旧、不支持高版本 ES 语法，PPTist 这种较新的前端项目建议使用 Chrome、Edge 或新版 Safari，老旧的浏览器内核很容易白屏。

还有一个坑是 Docker 镜像的静态资源没有清理旧文件。重新构建镜像时，如果使用 COPY 覆盖已有目录，Nginx 镜像里旧哈希文件可能残留，但一般不影响访问。真正需要关注的是浏览器缓存，尤其前端资源名都带哈希，更新版本后旧缓存如果能自动失效就不必手动清，前提是你构建时保持了正确的资源哈希。

6.3 Docker 环境本身的老问题

从环境维度看，最常见的异常集中在 Windows Docker 和镜像下载上。

Windows Docker Desktop 如果启动失败，提示虚拟化支持没有开启，十有八九是 BIOS 里虚拟化技术被关了，或者 WSL2/Hyper-V 功能没有启用。先去 BIOS 检查虚拟化开关，再在 Windows 功能里启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”，然后重启。这个过程本质上和 PPTist 没关系，但又是整套部署的基础，绕不过去。

镜像下载慢是另一个高频痛点。Docker Hub 在国内的访问速度有时候很不理想。配置镜像加速器的方法是在 Docker daemon 的配置文件中添加 registry-mirrors，选一个你所在云厂商提供的加速地址，保存后重启 Docker 服务。如果你所在网络能正常访问 Docker Hub，这一步也可以跳过。

6.4 “文件不见了”不是 bug，是架构选择

运行一段时间后，一定会有同事问：我昨天做的 PPT 怎么打不开了？这大概率不是服务故障，而是没有理解前面讲的数据边界。PPTist 没有服务端存储，编辑数据默认在浏览器本地，清缓存、换浏览器、换电脑都会导致找不回之前的文件。

所以在团队里推广时，我会把使用规范写清楚：

• 重要演示文稿完成后立刻导出工程文件