由博主开发的docker镜像，现已发布在dokcer hub上 grayfalcon/excalicloudstore 通过 Docker 单机部署 和 Docker Compose 部署 两种方式，快速使用 grayfalcon/excalicloudstore 镜像（基于 Excalidraw 开发，支持 S3 兼容存储的云端绘图工具）。

一、前提条件

在开始部署前，请确保您的环境已满足以下要求：

  1. 安装 Docker Engine（参考：Docker 官方安装文档）
    • Linux 系统：需确保 Docker 服务已启动（systemctl start docker）
    • Windows/macOS 系统：安装 Docker Desktop 并启动
  2. （可选）安装 Docker Compose（若使用 Compose 部署，参考：Docker Compose 安装文档）
  3. 准备好 S3 兼容存储配置（如 AWS S3、七牛云 Kodo、阿里云 OSS 等），需包含：
    • 访问密钥（Access Key ID）
    • 秘密密钥（Secret Access Key）
    • 存储区域（Region）
    • 终端节点（Endpoint）
    • 存储桶名称（Bucket Name）

二、方式一：Docker 单机部署

适合快速启动单个容器，步骤简单，适合测试或小型场景。

1. 核心部署命令

将以下命令中的 占位符（如 your_access_key_here） 替换为您的实际配置，直接在终端执行：

bash

 1# Linux/macOS 系统（续行符为 \）
 2docker run -d \
 3  -p 8080:80 \  # 宿主机端口:容器内端口（容器内默认80，可修改宿主机端口如 80:80）
 4  --name excalicloudstore \  # 容器名称（可自定义）
 5  --restart unless-stopped \  # 容器意外退出时自动重启
 6  -e PORT=3001 \  # 后端服务端口（容器内固定，无需修改）
 7  -e NODE_ENV=production \  # 环境类型（production 生产环境，development 开发环境）
 8  -e AWS_ACCESS_KEY_ID=your_access_key_here \  # 替换为 S3 访问密钥
 9  -e AWS_SECRET_ACCESS_KEY=your_secret_key_here \  # 替换为 S3 秘密密钥
10  -e S3_REGION=your_s3_region_here \  # 替换为 S3 区域（如 cn-east-1、us-east-1）
11  -e S3_ENDPOINT=your_s3_endpoint_here \  # 替换为 S3 终端节点
12  -e S3_BUCKET=your_s3_bucket_name_here \  # 替换为 S3 存储桶名称
13  -e STORAGE_PATH_PREFIX=Excalidraw/web_canvas/ \  # S3 存储路径前缀（可自定义，如无需求保持默认）
14  -e S3_FORCE_PATH_STYLE=true \  # 强制使用路径风格访问 S3（兼容多数存储服务）
15  -e S3_TLS=false \  # 是否启用 TLS（true 为 HTTPS，false 为 HTTP，根据 S3 配置选择）
16  grayfalcon/excalicloudstore:latest  # 镜像名称（:latest 为最新版本，可指定具体版本如 :v1）

powershell

 1# Windows PowerShell 系统（续行符为 `）
 2docker run -d `
 3  -p 8080:80 `
 4  --name excalicloudstore `
 5  --restart unless-stopped `
 6  -e PORT=3001 `
 7  -e NODE_ENV=production `
 8  -e AWS_ACCESS_KEY_ID=your_access_key_here `
 9  -e AWS_SECRET_ACCESS_KEY=your_secret_key_here `
10  -e S3_REGION=your_s3_region_here `
11  -e S3_ENDPOINT=your_s3_endpoint_here `
12  -e S3_BUCKET=your_s3_bucket_name_here `
13  -e STORAGE_PATH_PREFIX=Excalidraw/web_canvas/ `
14  -e S3_FORCE_PATH_STYLE=true `
15  -e S3_TLS=false `
16  grayfalcon/excalicloudstore:latest

2. 部署后验证

  1. 查看容器状态：确认容器是否正常启动

    bash

    1docker ps | grep excalicloudstore

    若 STATUS 为 Up X minutes，表示启动成功。

  2. 访问应用：打开浏览器，输入 http://宿主机IP:8080（如本地部署则为 http://localhost:8080），即可进入 Excalidraw 绘图页面。

  3. 查看日志：若启动失败或应用异常，可查看日志排查问题

    bash

    1docker logs -f excalicloudstore

三、方式二：Docker Compose 部署

适合多服务协同（如后续需添加数据库、后端服务等），配置文件化管理，便于维护和扩展。

1. 创建 Compose 配置文件

在任意目录下创建 docker-compose.yml 文件，内容如下（替换占位符为实际配置）：

yaml

 1version: "3.8"  # 兼容大部分 Docker Compose 版本
 2
 3services:
 4  excalicloudstore:
 5    image: grayfalcon/excalicloudstore:latest  # 镜像名称
 6    container_name: excalicloudstore  # 容器名称
 7    restart: unless-stopped  # 自动重启策略
 8    ports:
 9      - "8080:80"  # 端口映射（宿主机端口:容器内端口）
10    environment:
11      # 核心环境变量（替换占位符）
12      - PORT=3001
13      - NODE_ENV=production
14      - AWS_ACCESS_KEY_ID=your_access_key_here
15      - AWS_SECRET_ACCESS_KEY=your_secret_key_here
16      - S3_REGION=your_s3_region_here
17      - S3_ENDPOINT=your_s3_endpoint_here
18      - S3_BUCKET=your_s3_bucket_name_here
19      - STORAGE_PATH_PREFIX=Excalidraw/web_canvas/
20      - S3_FORCE_PATH_STYLE=true
21      - S3_TLS=false
22    # （可选）挂载目录（如需持久化配置或日志，可添加）
23    # volumes:
24    #   - ./excalidraw-logs:/var/log/excalidraw  # 日志持久化
25    #   - ./excalidraw-config:/opt/node_app/config  # 配置持久化

2. 启动服务

在 docker-compose.yml 所在目录执行以下命令：

bash

1# 后台启动服务（-d 表示 detached 模式）
2docker compose up -d
3
4# 查看服务状态
5docker compose ps

3. 停止 / 删除服务

bash

1# 停止服务（容器保留）
2docker compose stop
3
4# 停止并删除服务（容器、网络会被删除，挂载卷保留）
5docker compose down

四、环境变量说明

环境变量作用说明是否必填示例值
PORT容器内后端服务端口（固定为 3001，无需修改）否3001
NODE_ENV环境类型（生产环境用 production）否production / development
AWS_ACCESS_KEY_IDS3 兼容存储的访问密钥是AKIAXXXXXXXXXXXXXXXX
AWS_SECRET_ACCESS_KEYS3 兼容存储的秘密密钥是XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
S3_REGIONS3 存储区域是cn-east-1（七牛）、us-east-1（AWS）
S3_ENDPOINTS3 终端节点（兼容存储的 API 地址）是https://s3-cn-east-1.qiniucs.com
S3_BUCKET用于存储绘图文件的 S3 存储桶名称是excalidraw-storage
STORAGE_PATH_PREFIXS3 存储路径前缀（文件会存放在该路径下）否Excalidraw/web_canvas/
S3_FORCE_PATH_STYLE强制路径风格访问（兼容非 AWS S3 服务）否true（推荐）/false
S3_TLS是否启用 TLS（HTTPS）访问 S3否true（HTTPS）/ false（HTTP）

五、常见问题排查

  1. 容器启动失败，日志显示「S3 连接超时」

    • 检查 S3_ENDPOINT、S3_REGION 是否正确（避免端口或域名错误）；
    • 确认 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 是否有权限访问该存储桶；
    • 若使用私有网络，需确保宿主机能访问 S3 终端节点（可通过 curl 你的S3_ENDPOINT 测试连通性）。

  2. 浏览器访问 http://localhost:8080 无响应

    • 检查端口映射是否正确（如宿主机 8080 端口是否被占用，可换用 8081 等其他端口）；
    • 执行 docker ps 确认容器 STATUS 为 Up 状态，若退出则查看日志（docker logs excalicloudstore）；
    • 远程部署时，需确保宿主机防火墙开放了对应的端口（如 Linux 执行 ufw allow 8080）。

  3. 绘图文件无法保存到 S3

    • 检查存储桶是否存在，且密钥是否有「写入」权限；
    • 确认 S3_TLS 配置与终端节点协议一致（如 Endpoint 是 HTTP，则 S3_TLS=false）。

六、注意事项

  1. 敏感信息安全：避免将 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 硬编码到命令或配置文件中，生产环境建议使用 Docker Secrets 或 环境变量文件（如 .env）管理（需在 Compose 中通过 env_file: .env 引用）。
  2. 镜像版本：生产环境建议指定具体版本（如 grayfalcon/excalicloudstore:v1），避免使用 latest（可能因版本更新导致兼容性问题）。
  3. 端口冲突：若宿主机 8080 端口已被占用，可修改 -p 参数的宿主机端口（如 -p 80:80 直接使用 80 端口，需 root 权限）。