mirror of
https://github.com/Dvorinka/excalidraw-full.git
synced 2026-06-05 06:32:56 +00:00
Update README and docker-compose; add Chinese README
Expanded and clarified the main README with new features, configuration, and deployment instructions. Added a Chinese translation (README_zh.md). Updated docker-compose.yml to improve volume and env file mounting.
This commit is contained in:
Yuzhong Zhang
@@ -1,43 +1,103 @@
|
||||
# Excalidraw Complete: A Self-Hosted Solution
|
||||
# Excalidraw Complete: Your Self-Hosted, Cloud-Ready Collaboration Platform
|
||||
|
||||
Excalidraw Complete simplifies the deployment of Excalidraw, bringing an
|
||||
all-in-one solution to self-hosting this versatile virtual whiteboard. Designed
|
||||
for ease of setup and use, Excalidraw Complete integrates essential features
|
||||
into a single Go binary. This solution encompasses:
|
||||
|
||||
|
||||
- The intuitive Excalidraw frontend UI for seamless user experience.
|
||||
- An integrated data layer ensuring fast and efficient data handling based on different data providers.
|
||||
- A socket.io implementation to enable real-time collaboration among users.
|
||||
Excalidraw Complete has evolved. It's no longer just a simple wrapper for Excalidraw, but a powerful, self-hosted collaboration platform with a "Bring Your Own Cloud" (BYOC) philosophy. It provides user authentication, multi-canvas management, and the unique ability to connect directly to your own cloud storage from the frontend.
|
||||
|
||||
The project goal is to alleviate the setup complexities traditionally associated with self-hosting Excalidraw, especially in scenarios requiring data persistence and collaborative functionalities.
|
||||
The core idea is to let the backend handle user identity while giving you, the user, full control over where your data is stored.
|
||||
|
||||
## Installation
|
||||
## Key Features
|
||||
|
||||
To get started, download the latest release binary:
|
||||
- **GitHub Authentication**: Secure sign-in using GitHub OAuth.
|
||||
- **Multi-Canvas Management**: Users can create, save, and manage multiple drawing canvases.
|
||||
- **Flexible Data Storage (BYOC)**:
|
||||
- **Default Backend Storage**: Out-of-the-box support for saving canvases on the server's storage (SQLite, Filesystem, S3).
|
||||
- **Direct Cloud Connection**: The frontend can connect directly to your own cloud services like **Cloudflare KV** or **Amazon S3** for ultimate data sovereignty. Your credentials never touch our server.
|
||||
- **Real-time Collaboration**: The classic Excalidraw real-time collaboration is fully supported.
|
||||
- **Secure OpenAI Proxy**: An optional backend proxy for using OpenAI's GPT-4 Vision features, keeping your API key safe.
|
||||
- **All-in-One Binary**: The entire application, including the patched frontend and backend server, is compiled into a single Go binary for easy deployment.
|
||||
|
||||
## Frontend Canvas Storage Strategies
|
||||
|
||||
- **IndexedDB**: A fast, secure, and scalable key-value store. No need to configure anything. Not login required.
|
||||
- **Backend Storage**: The backend can save the canvas to the server's storage (SQLite, Filesystem, S3). Synchronized in different devices.
|
||||
- **Cloudflare KV**: A fast, secure, and scalable key-value store. Need to setup cloudlfare worker and DO spaces.
|
||||
- **Amazon S3**: A reliable, scalable, and inexpensive object storage service.
|
||||
|
||||
## Installation & Running
|
||||
|
||||
One Click Docker run [Excalidraw-Full](https://github.com/BetterAndBetterII/excalidraw-full).
|
||||
|
||||
```bash
|
||||
# Visit https://github.com/PatWie/excalidraw-complete/releases/ for the download URL
|
||||
wget <binary-download-url>
|
||||
chmod +x excalidraw-complete
|
||||
./excalidraw-complete
|
||||
# Example for Linux
|
||||
git clone https://github.com/BetterAndBetterII/excalidraw-full.git
|
||||
cd excalidraw-full
|
||||
touch ./excalidraw.db # IMPORTANT: Initialize the SQLite DB, OTHERWISE IT WILL NOT START
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Once launched, Excalidraw Complete is accessible at `localhost:3002`, ready for
|
||||
drawing and collaboration.
|
||||
The server will start, and you can access the application at `http://localhost:3002`.
|
||||
|
||||
### Configuration
|
||||
## Configuration
|
||||
|
||||
Excalidraw Complete adapts to your preferences with customizable storage solutions, adjustable via the `STORAGE_TYPE` environment variable:
|
||||
Configuration is managed via environment variables. For a full template, see the `.env.example` section below.
|
||||
|
||||
- **Filesystem:** Opt for `STORAGE_TYPE=filesystem` and define `LOCAL_STORAGE_PATH` to use a local directory.
|
||||
- **SQLite:** Select `STORAGE_TYPE=sqlite` with `DATA_SOURCE_NAME` for local SQLite storage, including the option for `:memory:` for ephemeral data.
|
||||
- **AWS S3:** Choose `STORAGE_TYPE=s3` and specify `S3_BUCKET_NAME` to leverage S3 bucket storage, ideal for cloud-based solutions.
|
||||
### 1. Backend Configuration (Required)
|
||||
|
||||
These flexible configurations ensure Excalidraw Complete fits seamlessly into your existing setup, whether on-premise or in the cloud.
|
||||
You must configure GitHub OAuth and a JWT secret for the application to function.
|
||||
|
||||
- `GITHUB_CLIENT_ID`: Your GitHub OAuth App's Client ID.
|
||||
- `GITHUB_CLIENT_SECRET`: Your GitHub OAuth App's Client Secret.
|
||||
- `GITHUB_REDIRECT_URL`: The callback URL. For local testing, this is `http://localhost:3002/auth/github/callback`.
|
||||
- `JWT_SECRET`: A strong, random string for signing session tokens. Generate one with `openssl rand -base64 32`.
|
||||
- `OPENAI_API_KEY`: Your secret key from OpenAI.
|
||||
- `OPENAI_BASE_URL`: (Optional) For using compatible APIs like Azure OpenAI.
|
||||
|
||||
### 2. Default Storage (Optional, but Recommended)
|
||||
|
||||
This configures the server's built-in storage, used by default.
|
||||
|
||||
- `STORAGE_TYPE`: `memory` (default), `sqlite`, `filesystem`, or `s3`.
|
||||
- `DATA_SOURCE_NAME`: Path for the SQLite DB (e.g., `excalidraw.db`).
|
||||
- `LOCAL_STORAGE_PATH`: Directory for filesystem storage.
|
||||
- `S3_BUCKET_NAME`, `AWS_REGION`, etc.: For S3 storage.
|
||||
|
||||
### 3. OpenAI Proxy (Optional)
|
||||
|
||||
To enable AI features, set your OpenAI API key.
|
||||
|
||||
- `OPENAI_API_KEY`: Your secret key from OpenAI.
|
||||
- `OPENAI_BASE_URL`: (Optional) For using compatible APIs like Azure OpenAI.
|
||||
|
||||
### 4. Frontend Configuration
|
||||
|
||||
Frontend storage adapters (like Cloudflare KV, S3) are configured directly in the application's UI settings after you log in. This is by design: your private cloud credentials are only ever stored in your browser's session and are never sent to the backend server.
|
||||
|
||||
### Example `.env.example`
|
||||
|
||||
Create a `.env` file in the project root and add the following, filling in your own values.
|
||||
|
||||
```env
|
||||
# Backend Server Configuration
|
||||
# Get from https://github.com/settings/developers
|
||||
GITHUB_CLIENT_ID=your_github_client_id
|
||||
GITHUB_CLIENT_SECRET=your_github_client_secret
|
||||
GITHUB_REDIRECT_URL=http://localhost:3002/auth/github/callback
|
||||
|
||||
# Generate with: openssl rand -base64 32
|
||||
JWT_SECRET=your_super_secret_jwt_string
|
||||
|
||||
# Default Storage (SQLite)
|
||||
STORAGE_TYPE=sqlite
|
||||
DATA_SOURCE_NAME=excalidraw.db
|
||||
|
||||
# Optional OpenAI Proxy
|
||||
OPENAI_API_KEY=sk-your_openai_api_key
|
||||
```
|
||||
|
||||
## Building from Source
|
||||
|
||||
Interested in contributing or customizing? Build Excalidraw Complete from source with these steps:
|
||||
The process is similar to before, but now requires the Go backend to be built.
|
||||
|
||||
### Using Docker (Recommended)
|
||||
|
||||
@@ -46,56 +106,35 @@ Interested in contributing or customizing? Build Excalidraw Complete from source
|
||||
git clone https://github.com/PatWie/excalidraw-complete.git --recursive
|
||||
cd excalidraw-complete
|
||||
|
||||
# Build the Docker image (includes frontend and backend)
|
||||
# Build the Docker image
|
||||
# This handles the frontend build, patching, and Go backend compilation.
|
||||
docker build -t excalidraw-complete -f excalidraw-complete.Dockerfile .
|
||||
|
||||
# Run the container
|
||||
docker run -p 3002:3002 excalidraw-complete
|
||||
# Run the container, providing the environment variables
|
||||
docker run -p 3002:3002 \
|
||||
-e GITHUB_CLIENT_ID="your_id" \
|
||||
-e GITHUB_CLIENT_SECRET="your_secret" \
|
||||
-e GITHUB_REDIRECT_URL="http://localhost:3002/auth/github/callback" \
|
||||
-e JWT_SECRET="your_jwt_secret" \
|
||||
-e STORAGE_TYPE="sqlite" \
|
||||
-e DATA_SOURCE_NAME="excalidraw.db" \
|
||||
-e OPENAI_API_KEY="your_openai_api_key" \
|
||||
excalidraw-complete
|
||||
```
|
||||
|
||||
### Manual Build
|
||||
|
||||
```bash
|
||||
# Clone and prepare the Excalidraw frontend
|
||||
git clone https://github.com/PatWie/excalidraw-complete.git --recursive
|
||||
cd ./excalidraw-complete/excalidraw
|
||||
|
||||
# Apply frontend patches
|
||||
git apply ../frontend.patch
|
||||
|
||||
# Build frontend
|
||||
npm install
|
||||
cd excalidraw-app
|
||||
npm run build:app:docker
|
||||
cd ../../
|
||||
|
||||
# Copy frontend build to correct location
|
||||
cp -r excalidraw/excalidraw-app/build frontend/
|
||||
|
||||
# Build Go application
|
||||
go build -o excalidraw-complete main.go
|
||||
```
|
||||
|
||||
(Optional) Replace `localhost:3002` inside of `main.go` with your domain name if you want to use a reverse proxy
|
||||
(Optional) Replace `"ssl=!0", "ssl=0"` with `"ssl=!0", "ssl=1"` if you want to use HTTPS
|
||||
(Optional) Replace `"ssl:!0", "ssl:0"` with `"ssl:!0", "ssl:1"` if you want to use HTTPS
|
||||
|
||||
Declare environment variables if you want any (see section above)
|
||||
Example: `STORAGE_TYPE=sqlite DATA_SOURCE_NAME=/tmp/excalidb.sqlite`
|
||||
|
||||
Start the server:
|
||||
|
||||
```bash
|
||||
go run main.go --listen=":3002"
|
||||
|
||||
STORAGE_TYPE=sqlite DATA_SOURCE_NAME=test.db go run main.go --loglevel debug --listen=":3002"
|
||||
STORAGE_TYPE=filesystem LOCAL_STORAGE_PATH=/tmp/excalidraw/ go run main.go --loglevel debug --listen=":3002"
|
||||
```
|
||||
|
||||
Excalidraw Complete is now running on your machine, ready to bring your collaborative whiteboard ideas to life.
|
||||
|
||||
1. **Build Frontend**: Follow the steps in the original README to patch and build the Excalidraw frontend inside the `excalidraw/` submodule.
|
||||
2. **Copy Frontend**: Ensure the built frontend from `excalidraw/excalidraw-app/build` is copied to the `frontend/` directory in the root.
|
||||
3. **Build Go Backend**:
|
||||
```bash
|
||||
go build -o excalidraw-complete main.go
|
||||
```
|
||||
4. **Run**:
|
||||
```bash
|
||||
# Set environment variables first
|
||||
./excalidraw-complete
|
||||
```
|
||||
---
|
||||
|
||||
Excalidraw is a fantastic tool, but self-hosting it can be tricky. I welcome
|
||||
your contributions to improve Excalidraw Complete — be it through adding new
|
||||
features, improving existing ones, or bug reports.
|
||||
Excalidraw is a fantastic tool. This project aims to make a powerful, data-secure version of it accessible to everyone. Contributions are welcome!
|
||||
|
||||
+138
@@ -0,0 +1,138 @@
|
||||
# Excalidraw Complete: 您的自托管、云就绪协作平台
|
||||
|
||||
Excalidraw Complete 已经进化。它不再仅仅是 Excalidraw 的一个简单封装，而是一个强大的、自托管的协作平台，秉承"自带云"（BYOC - Bring Your Own Cloud）的理念。它提供用户认证、多画板管理，以及从前端直接连接到您自己的云存储的独特能力。
|
||||
|
||||
其核心思想是让后端处理用户身份，同时让您（用户）完全控制数据的存储位置。
|
||||
|
||||
## 主要特性
|
||||
|
||||
- **GitHub 认证**：使用 GitHub OAuth 安全登录。
|
||||
- **多画板管理**：用户可以创建、保存和管理多个绘图画板。
|
||||
- **灵活的数据存储 (BYOC)**：
|
||||
- **默认后端存储**：开箱即用地支持将画板保存在服务器的存储中（SQLite、文件系统、S3）。
|
||||
- **直接云连接**：前端可以直接连接到您自己的云服务，如 **Cloudflare KV** 或 **Amazon S3**，以实现终极数据主权。您的凭证永远不会触及我们的服务器。
|
||||
- **实时协作**：完全支持经典的 Excalidraw 实时协作功能。
|
||||
- **安全的 OpenAI 代理**：一个可选的后端代理，用于使用 OpenAI 的 GPT-4 Vision 功能，确保您的 API 密钥安全。
|
||||
- **一体化二进制文件**：整个应用程序，包括打过补丁的前端和后端服务器，都被编译成一个单一的 Go 二进制文件，便于部署。
|
||||
|
||||
## 前端画板存储策略
|
||||
|
||||
- **IndexedDB**: 一种快速、安全且可扩展的键值存储。无需任何配置，也无需登录。
|
||||
- **后端存储**: 后端可以将画板保存到服务器的存储中（SQLite、文件系统、S3）。可在不同设备间同步。
|
||||
- **Cloudflare KV**: 一种快速、安全且可扩展的键值存储。需要设置 Cloudflare Worker 和 DO Spaces。
|
||||
- **Amazon S3**: 一种可靠、可扩展且经济的对象存储服务。
|
||||
|
||||
## 安装与运行
|
||||
|
||||
一键 Docker 运行 [Excalidraw-Full](https://github.com/BetterAndBetterII/excalidraw-full).
|
||||
|
||||
```bash
|
||||
# Linux 示例
|
||||
git clone https://github.com/BetterAndBetterII/excalidraw-full.git
|
||||
cd excalidraw-full
|
||||
touch ./excalidraw.db # 重要：初始化 SQLite 数据库，否则无法启动
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
服务器将启动，您可以在 `http://localhost:3002` 访问该应用。
|
||||
|
||||
## 配置
|
||||
|
||||
配置通过环境变量进行管理。有关完整模板，请参阅下面的 `.env.example` 部分。
|
||||
|
||||
### 1. 后端配置 (必需)
|
||||
|
||||
您必须配置 GitHub OAuth 和 JWT 密钥才能使应用程序正常运行。
|
||||
|
||||
- `GITHUB_CLIENT_ID`: 您的 GitHub OAuth App 的 Client ID。
|
||||
- `GITHUB_CLIENT_SECRET`: 您的 GitHub OAuth App 的 Client Secret。
|
||||
- `GITHUB_REDIRECT_URL`: 回调 URL。对于本地测试，这是 `http://localhost:3002/auth/github/callback`。
|
||||
- `JWT_SECRET`: 用于签署会话令牌的强随机字符串。使用 `openssl rand -base64 32` 生成一个。
|
||||
- `OPENAI_API_KEY`: 您在 OpenAI 的秘密密钥。
|
||||
- `OPENAI_BASE_URL`: (可选) 用于使用兼容的 API，如 Azure OpenAI。
|
||||
|
||||
### 2. 默认存储 (可选，但推荐)
|
||||
|
||||
这会配置服务器的内置存储，默认使用。
|
||||
|
||||
- `STORAGE_TYPE`: `memory` (默认), `sqlite`, `filesystem`, 或 `s3`。
|
||||
- `DATA_SOURCE_NAME`: SQLite 数据库的路径 (例如, `excalidraw.db`)。
|
||||
- `LOCAL_STORAGE_PATH`: 文件系统存储的目录。
|
||||
- `S3_BUCKET_NAME`, `AWS_REGION`, 等: 用于 S3 存储。
|
||||
|
||||
### 3. OpenAI 代理 (可选)
|
||||
|
||||
要启用 AI 功能，请设置您的 OpenAI API 密钥。
|
||||
|
||||
- `OPENAI_API_KEY`: 您在 OpenAI 的秘密密钥。
|
||||
- `OPENAI_BASE_URL`: (可选) 用于使用兼容的 API，如 Azure OpenAI。
|
||||
|
||||
### 4. 前端配置
|
||||
|
||||
前端存储适配器（如 Cloudflare KV, S3）在您登录后直接在应用程序的 UI 设置中配置。这是特意设计的：您的私有云凭证只存储在浏览器的会话中，绝不会发送到后端服务器。
|
||||
|
||||
### `.env.example` 示例
|
||||
|
||||
在项目根目录中创建一个 `.env` 文件，并添加以下内容，填入您自己的值。
|
||||
|
||||
```env
|
||||
# 后端服务器配置
|
||||
# 从 https://github.com/settings/developers 获取
|
||||
GITHUB_CLIENT_ID=your_github_client_id
|
||||
GITHUB_CLIENT_SECRET=your_github_client_secret
|
||||
GITHUB_REDIRECT_URL=http://localhost:3002/auth/github/callback
|
||||
|
||||
# 使用以下命令生成: openssl rand -base64 32
|
||||
JWT_SECRET=your_super_secret_jwt_string
|
||||
|
||||
# 默认存储 (SQLite)
|
||||
STORAGE_TYPE=sqlite
|
||||
DATA_SOURCE_NAME=excalidraw.db
|
||||
|
||||
# 可选的 OpenAI 代理
|
||||
OPENAI_API_KEY=sk-your_openai_api_key
|
||||
```
|
||||
|
||||
## 从源码构建
|
||||
|
||||
过程与之前类似，但现在需要构建 Go 后端。
|
||||
|
||||
### 使用 Docker (推荐)
|
||||
|
||||
```bash
|
||||
# 克隆仓库及其子模块
|
||||
git clone https://github.com/PatWie/excalidraw-complete.git --recursive
|
||||
cd excalidraw-complete
|
||||
|
||||
# 构建 Docker 镜像
|
||||
# 此过程会处理前端构建、打补丁和 Go 后端编译。
|
||||
docker build -t excalidraw-complete -f excalidraw-complete.Dockerfile .
|
||||
|
||||
# 运行容器，并提供环境变量
|
||||
docker run -p 3002:3002 \
|
||||
-e GITHUB_CLIENT_ID="your_id" \
|
||||
-e GITHUB_CLIENT_SECRET="your_secret" \
|
||||
-e GITHUB_REDIRECT_URL="http://localhost:3002/auth/github/callback" \
|
||||
-e JWT_SECRET="your_jwt_secret" \
|
||||
-e STORAGE_TYPE="sqlite" \
|
||||
-e DATA_SOURCE_NAME="excalidraw.db" \
|
||||
-e OPENAI_API_KEY="your_openai_api_key" \
|
||||
excalidraw-complete
|
||||
```
|
||||
|
||||
### 手动构建
|
||||
|
||||
1. **构建前端**: 按照原始 README 中的步骤，在 `excalidraw/` 子模块内打补丁并构建 Excalidraw 前端。
|
||||
2. **复制前端**: 确保将 `excalidraw/excalidraw-app/build` 中构建好的前端文件复制到根目录的 `frontend/` 目录下。
|
||||
3. **构建 Go 后端**:
|
||||
```bash
|
||||
go build -o excalidraw-complete main.go
|
||||
```
|
||||
4. **运行**:
|
||||
```bash
|
||||
# 首先设置环境变量
|
||||
./excalidraw-complete
|
||||
```
|
||||
---
|
||||
|
||||
Excalidraw 是一个很棒的工具。该项目旨在让每个人都能使用一个功能强大、数据安全的版本。欢迎贡献！
|
||||
+2
-3
@@ -7,6 +7,5 @@ services:
|
||||
- "3002:3002"
|
||||
volumes:
|
||||
- ./data:/root/data
|
||||
- ./excalidraw.db:/root/excalidraw.db
|
||||
env_file:
|
||||
- .env
|
||||
- ./excalidraw.db:/root/excalidraw.db:Z
|
||||
- ./.env:/root/.env
|
||||
|
||||
Reference in New Issue
Block a user