本地部署Excalidraw手绘白板指南-开发者社区

本地部署 Excalidraw 手绘白板指南

在远程协作日益频繁的今天，一个轻量、直观且安全的可视化工具几乎成了每个技术团队的刚需。无论是画架构草图、梳理业务流程，还是开一场即兴的头脑风暴，一张“能写会动”的数字白板往往比复杂的建模软件更高效。而Excalidraw正是这样一款让人眼前一亮的开源工具——它用极简的手绘风格还原了纸笔书写的自然感，却又无缝集成了现代协作能力。

更难得的是，它的整个技术栈设计得非常友好：前端基于 React + Canvas 实现，后端协作服务使用 Node.js 和 WebSocket，整体结构清晰，部署成本低。尤其适合希望将白板系统私有化部署、保障数据不出内网的企业或个人开发者。

本文不讲概念堆砌，直接带你从零开始，在本地快速搭建一个支持实时协作、具备基础持久化能力的 Excalidraw 私有实例。全程基于 Docker 部署，兼顾效率与可维护性，最后还会补充手动构建静态版本的方法，满足不同场景需求。

环境准备：别让依赖卡住第一步

动手前先确认你的主机已经装好了以下组件：

Git：用来拉取官方源码
Docker（建议 20.10+）：容器运行时核心
Docker Compose v2.x：注意是新版docker compose（无横杠），不是旧版docker-compose

💡 小贴士：如果你还在用老版本的 Compose 插件，可以通过以下命令检查：
bash docker compose version
如果提示找不到命令，说明需要安装或升级。参考官方文档：
https://docs.docker.com/compose/install/

内存方面，至少预留 512MB 给容器使用。网络要通畅，毕竟第一次部署得下载镜像。

一键启动：用 Docker 快速跑起来

Excalidraw 官方提供了完整的docker-compose.yml模板，省去了自己打包前端的麻烦。我们只需要几步就能让服务跑起来。

首先克隆仓库：

git clone https://github.com/excalidraw/excalidraw.git cd excalidraw

这个仓库不仅包含前端代码，还有生产用的 Nginx 镜像配置和开发服务器设置。

接着直接启动默认服务：

docker compose up -d

这条命令会自动完成三件事：

拉取excalidraw/excalidraw镜像（基于 Alpine + Nginx 的静态站点）
后台运行容器
把宿主机的3000端口映射到容器的80，即访问 http://localhost:3000

等几秒后查看运行状态：

docker ps | grep excalidraw

你应该能看到类似输出：

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES abc123def456 excalidraw/excalidraw "nginx -g 'daemon of…" 2 minutes ago Up 2 mins 0.0.0.0:3000->80/tcp excalidraw-excalidraw-1

此时打开浏览器访问 http://localhost:3000，就能看到干净清爽的手绘界面了。

但别高兴太早——这时候的 Excalidraw 只是一个“单机版”，没有协作功能，刷新页面就丢内容。要想真正发挥它的潜力，还得加上后端同步服务。

自定义配置：改端口、设环境变量

默认映射到3000端口虽然方便，但在实际环境中容易冲突。比如你本机可能已经有其他服务占用了这个端口。所以最好提前修改一下配置。

编辑项目根目录下的docker-compose.yml文件：

vi docker-compose.yml

找到services.excalidraw.ports这一项，改成你喜欢的端口，比如3002：

services: excalidraw: image: excalidraw/excalidraw ports: - "3002:80" environment: - NODE_ENV=production

这里顺手加上NODE_ENV=production是个好习惯。它可以关闭开发模式下的调试日志，减少不必要的输出，也让前端资源加载更快一点。

改完之后重启服务：

docker compose down docker compose up -d

现在访问 http://localhost:3002 即可生效。

加入协作能力：让多人同时画画

这才是 Excalidraw 的灵魂所在。默认的单容器部署只是个静态页面，真正的“实时协同编辑”依赖于另一个独立的服务：excalidraw-room。

这是一个轻量级的 WebSocket 服务，负责处理客户端之间的连接、消息广播和房间管理。它的设计很巧妙——前端会自动探测是否存在名为room的服务，如果发现，就会自动启用协作模式。

所以我们只需在docker-compose.yml中新增一个服务即可：

version: '3' services: excalidraw: image: excalidraw/excalidraw ports: - "3002:80" environment: - NODE_ENV=production depends_on: - room room: image: excalidraw/excalidraw-room environment: - HTTP_SERVER_PORT=80 - COLLABORATION_PORT=443 expose: - "80"

几点说明：

depends_on确保前端等待room服务启动后再运行，避免连接失败。
COLLABORATION_PORT=443是协议要求，即使实际通信走的是 80 端口，也建议保留该变量。
expose: 80表示该端口仅对内部网络开放，无需对外暴露，提升安全性。

保存后重新部署：

docker compose down && docker compose up -d

刷新网页，点击右上角的「Share」按钮，你会发现多了一个选项：“Collaborative realtime editing”。点击后生成的链接就可以分享给同事，邀请他们加入同一个画布协同编辑。

⚠️ 注意：当前这种部署方式下，所有房间数据都存在内存里。一旦容器重启，所有正在进行的协作会话都会中断，未导出的内容也会丢失。这在演示或临时会议中问题不大，但如果想长期使用，就得考虑持久化方案。

数据持久化尝试：留住关键记录

虽然excalidraw-room目前不支持数据库存储（如 PostgreSQL 或 Redis），但它会在运行时生成一些日志文件，记录连接事件和错误信息。我们可以把这些日志挂载出来，便于排查问题。

在room服务中添加卷挂载：

room: image: excalidraw/excalidraw-room environment: - HTTP_SERVER_PORT=80 - COLLABORATION_PORT=443 expose: - "80" volumes: - ./logs:/app/logs

下次启动时，容器内的/app/logs目录就会映射到宿主机的./logs文件夹，日志得以保留。

当然，这不是真正意义上的“数据持久化”。如果你想保存画布内容，目前最可行的方式是在客户端手动导出为.excalidraw文件（本质是 JSON），然后集中归档管理。未来如果有社区插件或自研后端接入，也可以通过扩展room服务来实现自动备份。

使用体验：不只是好看，更要好用

打开 http://localhost:3002，你会被那种“纸上作画”的质感吸引。左侧工具栏简洁明了，右侧属性面板提供颜色、粗细、字体等调节项，顶部菜单则藏着导出、共享、主题切换等功能。

常用功能一览：

功能	说明
🖊️ 手绘线条	支持压感笔触，模拟真实书写抖动感
▢ 图形绘制	包括矩形、圆形、箭头、菱形判断等流程图元素
🧩 对齐与分布	自动吸附、智能辅助线提升排版效率
📤 导出图像	支持 PNG/SVG 格式，透明背景开箱即用
🔗 共享协作	获取链接即可发起实时会话
🎨 主题切换	支持亮色 / 暗色模式，保护夜间视力