本地部署 Excalidraw 手绘白板教程-育师

本地部署 Excalidraw 手绘白板教程

你有没有遇到过这样的场景：团队远程开会，想要快速画一张架构草图，却发现协作白板工具要么太重、要么数据不安全？这时候，Excalidraw 往往会成为那个“刚刚好”的选择——手绘风格亲切自然，界面干净无干扰，支持实时协作，还能端到端加密。更重要的是，它是开源的，意味着你可以完全掌控自己的数据。

如果你希望摆脱对在线服务的依赖，搭建一个只属于你或团队内部使用的私有化白板系统，那么本文就是为你准备的。我们将通过 Docker 快速部署一个稳定可用的 Excalidraw 实例，并可选地接入持久化协作能力，整个过程不到十分钟。

环境准备与基础要求

在动手之前，请先确认你的设备满足以下条件：

操作系统：Linux、macOS 或 Windows（推荐使用 WSL2）
Docker 已安装且运行正常，版本建议 ≥ 20.10
Docker Compose 插件已启用（现代 Docker Desktop 默认集成）
内存 ≥ 2GB，4GB 更佳以确保流畅体验
开放指定端口权限，默认使用3002，需避免被其他服务占用

💡 如果还未安装 Docker，可以访问 https://docs.docker.com/get-docker/ 下载对应平台的安装包。Windows 用户强烈建议启用 WSL2 后端，性能和兼容性更优。

Excalidraw 官方提供了托管在 GitHub Container Registry（ghcr.io）上的预构建镜像，无需编译前端代码即可直接运行。这意味着我们不需要拉仓库、装依赖、打包构建，真正实现“开箱即用”。

使用 Docker Compose 一键部署

最高效的方式是借助docker-compose.yml来管理容器生命周期。首先创建一个专用目录：

mkdir excalidraw-deploy && cd excalidraw-deploy

然后创建配置文件：

touch docker-compose.yml

将以下内容写入该文件：

version: '3.8' services: excalidraw: image: ghcr.io/excalidraw/excalidraw:latest container_name: excalidraw ports: - "3002:80" environment: - NODE_ENV=production restart: unless-stopped

这个配置虽然简洁，但已经足够支撑大多数本地或内网使用场景。下面是几个关键点的说明：

image: 直接使用官方发布的最新版镜像，自动保持更新。
ports: 将宿主机的3002端口映射到容器的80，因为镜像是基于 Nginx 托管静态资源的。
NODE_ENV=production: 启用生产模式，减少调试信息输出并优化加载性能。
restart: unless-stopped: 容器异常退出时自动重启，保障服务长期可用。

不需要复杂的反向代理或数据库支持，也不用担心前端打包问题——这一切都封装在镜像里了。

自定义端口与环境变量配置

如果你的3002端口已被占用，或者你想统一规划服务端口，只需修改ports字段即可。例如改为8080:80：

ports: - "8080:80"

之后通过http://localhost:8080即可访问。

此外，尽管 Excalidraw 主体功能对环境变量的需求较少，但仍有一些可选项可用于微调行为。比如关闭分析上报：

environment: - NODE_ENV=production - ALLOW_ANALYTICS=false

⚠️ 注意：当前版本中，Excalidraw 的核心逻辑运行在浏览器端，服务器仅用于提供 HTML 和静态资源。因此像用户认证、房间持久化等功能无法仅靠此配置实现，需要额外组件支持。

这也正是它轻量的原因之一：没有后端状态压力，部署简单，但也意味着要实现高级协作功能，得再往前走一步。

启动服务并验证运行状态

一切就绪后，执行命令启动容器：

docker compose up -d

你会看到类似输出：

Creating network "excalidraw-deploy_default" with the default driver Pulling excalidraw (ghcr.io/excalidraw/excalidraw:latest)... latest: Pulling from excalidraw/excalidraw Digest: sha256:abc123... Status: Downloaded newer image for ghcr.io/excalidraw/excalidraw:latest Creating excalidraw ... done

表示镜像已拉取完成，容器正在后台运行。

检查是否成功启动：

docker ps | grep excalidraw

预期输出如下：

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES abc123def456 ghcr.io/excalidraw/excalidraw:latest "/docker-entrypoint.…" 2 minutes ago Up 2 minutes 0.0.0.0:3002->80/tcp excalidraw

只要状态为Up，并且端口正确映射，就可以进行下一步访问了。

访问与使用手绘白板

打开浏览器，输入地址：

👉 http://localhost:3002

你会进入一个极简的手绘风格画布界面：左侧是工具栏，右侧是空白画布，顶部有导出和分享按钮。整体设计几乎没有学习成本，几分钟就能上手绘制流程图、UI 草图或系统架构图。

核心特性一览：

✅手绘风格渲染：所有图形自动带有轻微抖动效果，视觉上更接近真实笔迹，降低正式感带来的表达压力。
✅多格式导出：支持导出为 PNG、SVG，也可直接复制到剪贴板嵌入文档。
✅实时协作链接：点击右上角 “Share” 按钮，生成唯一房间 URL，分享给他人即可协同编辑。
✅离线可用：即使断网也能继续作图，网络恢复后内容可同步（前提是未关闭页面）。
✅AI 辅助绘图（实验性）：部分社区插件支持通过自然语言提示生成草图，适合快速原型构思。

🔐 所有协作数据均通过 WebSocket 在客户端之间传输，服务器不存储任何绘图内容，真正实现端到端加密，隐私更有保障。

无论是做技术方案讨论、产品需求脑暴，还是写博客配图，Excalidraw 都能让你的想法更快落地。

可选进阶：启用持久化协作与自定义存储

默认情况下，Excalidraw 的协作会话是临时的——一旦所有人离开房间，数据即消失。这适合一次性会议，但如果想长期保留某个项目白板，就需要引入外部协作服务器。

方案一：挂载自定义组件库（适用于团队模板复用）

你可以将常用的图形组合保存为组件库，并通过卷挂载方式注入容器：

volumes: - ./custom-lib.json:/usr/share/nginx/html/lib.json

这样每次启动时都会加载预设的资产库，提升团队一致性与效率。

方案二：部署独立房间服务器实现持久化协作

Excalidraw 提供了一个配套项目excalidraw-room，它是一个基于 WebSocket 的房间管理服务，能够维持长期存在的协作会话。

我们可以将其集成进docker-compose.yml：

version: '3.8' services: room-server: image: ghcr.io/excalidraw/excalidraw-room:latest environment: - PORT=3003 ports: - "3003:3003" restart: unless-stopped excalidraw: image: ghcr.io/excalidraw/excalidraw:latest environment: - COLLABORATION_URL=http://localhost:3003 ports: - "3002:80" restart: unless-stopped