Excalidraw 自托管存储版 Docker 镜像文档

1. 镜像概述和主要用途

本镜像基于 Excalidraw 开源项目（alswl/excalidraw-collaboration）构建，是其分支版本，核心特性为集成自托管存储功能。Excalidraw 是一款轻量级协作绘图工具，支持手绘风格图形绘制，本镜像在此基础上解决了原生版本依赖第三方存储的问题，允许用户将绘图数据存储在本地或自定义服务器环境中，适用于需要数据本地化、隐私保护或自定义存储配置的协作场景。

2. 核心功能和特性

2.1 基础绘图功能

• 支持手绘风格图形绘制，包含线条、形状、文本、箭头等基础元素
• 实时协作编辑，多用户同步操作
• 支持画布缩放、平移、图层管理
• 导出 PNG/SVG 格式文件，导入外部图像

2.2 自托管存储增强功能

• 数据本地化：绘图数据存储在用户自有服务器，避免第三方依赖
• 隐私保护：敏感数据无需上传至公共服务，符合企业/团队隐私合规要求
• 灵活存储配置：支持本地文件系统、自定义数据库（如 SQLite、PostgreSQL，需根据实际分支实现配置）
• 数据持久化：容器重启后数据不丢失（需正确配置存储卷）

3. 使用场景和适用范围

4. 使用方法和配置说明

4.1 前提条件

• 已安装 Docker Engine（20.10+ 版本推荐）
• 已安装 Docker Compose（可选，用于多容器管理）
• 服务器开放目标端口（默认 8080，可自定义）

4.2 镜像拉取

从 Docker Hub 或 GitHub Container Registry 拉取镜像（具体镜像名称以项目实际发布为准，此处假设镜像标签为 alswl/excalidraw-collaboration:latest）：

docker pull alswl/excalidraw-collaboration:latest

4.3 快速启动（单容器模式）

通过 docker run 命令快速启动容器，映射端口并挂载存储卷以持久化数据：

docker run -d \
  --name excalidraw-selfhosted \
  -p 8080:8080 \
  -v ./excalidraw-data:/app/storage \  # 挂载本地目录作为存储卷，持久化数据
  -e PORT=8080 \                      # 应用监听端口（需与容器端口映射一致）
  -e STORAGE_TYPE=local \             # 存储类型，可选 local 或其他支持的存储后端
  -e STORAGE_PATH=/app/storage \      # 存储路径（容器内路径，需与挂载卷对应）
  --restart unless-stopped \
  alswl/excalidraw-collaboration:latest

参数说明：

• -p 8080:8080：端口映射（宿主机端口:容器内端口）
• -v ./excalidraw-data:/app/storage：挂载宿主机目录 ./excalidraw-data 到容器内 /app/storage，用于持久化存储绘图数据
• --restart unless-stopped：容器退出时自动重启（除非手动停止）

4.4 环境变量配置

以下为常用环境变量（具体以项目实际支持为准，可参考 GitHub 源码 文档）：

4.5 Docker Compose 配置示例

对于复杂场景（如需集成数据库），可使用 docker-compose.yml 管理服务：

version: '3.8'

services:
  excalidraw:
    image: alswl/excalidraw-collaboration:latest
    container_name: excalidraw-selfhosted
    ports:
      - "8080:8080"
    volumes:
      - ./excalidraw-data:/app/storage  # 本地存储卷
    environment:
      - PORT=8080
      - STORAGE_TYPE=local
      - STORAGE_PATH=/app/storage
      - LOG_LEVEL=info
    restart: unless-stopped

  # （可选）若使用数据库存储，可添加数据库服务（如 PostgreSQL）
  # db:
  #   image: postgres:14
  #   volumes:
  #     - postgres-data:/var/lib/postgresql/data
  #   environment:
  #     - POSTGRES_PASSWORD=excalidraw_db_pass
  #     - POSTGRES_USER=excalidraw_db_user
  #     - POSTGRES_DB=excalidraw_db
  #   restart: unless-stopped

# volumes:
#   postgres-data:  # 数据库数据卷（若启用数据库服务）

启动命令：

docker-compose up -d

4.6 访问应用

容器启动后，通过浏览器访问 http://<宿主机IP>:8080 即可打开 Excalidraw 应用。首次访问无需注册，直接创建绘图并自动保存至自托管存储。

5. 数据备份与迁移

为避免数据丢失，需定期备份挂载的存储卷目录（如 ./excalidraw-data）。迁移时，将备份目录复制到新服务器，重新挂载即可恢复数据。

6. 注意事项

• 存储权限：确保宿主机挂载目录（如 ./excalidraw-data）权限正确（建议设置 755，避免容器内权限不足）
• 生产环境安全：生产环境中建议限制 CORS_ALLOWED_ORIGINS，并通过反向代理（如 Nginx）配置 HTTPS
• 版本更新：更新镜像前需备份数据，避免因版本兼容性导致数据损坏
• 存储后端扩展：若需使用数据库存储（如 PostgreSQL），需提前配置 DATABASE_URL 环境变量（格式参考数据库文档）