Colanode

开源且本地优先的协作工作区，支持自托管

Colanode 是一个一体化协作平台，旨在简化协作流程，同时将数据隐私和控制权放在首位。采用本地优先的设计理念，它帮助团队进行沟通、组织和项目管理——无论在线还是离线。使用 Colanode，您可以获得现代协作工具的灵活性，同时享受数据所有权带来的安心。

Colanode 能做什么？

• 实时聊天：通过团队和个人即时消息保持联系。
• 富文本页面：使用直观的编辑器创建文档、维基和笔记，类似于 Notion。
• 可自定义数据库：通过结构化数据、自定义字段和动态视图（表格、看板、日历）组织信息。
• 文件管理：在安全的工作区内轻松存储、共享和管理文件。

Colanode 为个人和团队打造，可适应您的需求，无论您是运行小型项目、管理团队还是在整个组织中协作。凭借其自托管模式，您可以在享受完善且功能丰富的体验的同时，保留对数据的完全控制权。

工作原理

Colanode 包含客户端应用（网页或桌面版）和自托管服务器。您可以通过单个应用连接到多个服务器，每个服务器包含一个或多个用于不同团队或项目的工作区。登录后，您可以选择一个工作区开始协作——发送消息、编辑页面或更新数据库记录。

本地优先工作流

您所做的所有更改首先保存到本地 SQLite 数据库，然后同步到服务器。后台进程处理此同步，因此即使您的计算机或服务器离线，您也可以继续工作。数据读取也在本地进行，确保您可以立即访问有权查看的任何内容。

并发编辑

Colanode 依靠无冲突复制数据类型（CRDTs）——由 Yjs 提供支持——允许对页面或数据库记录等条目进行实时协作。这意味着多人可以同时编辑，系统会优雅地合并所有人的更新。删除操作也作为特殊事务进行跟踪。消息和文件操作不支持并发编辑，使用更简单的数据库表。

要使用 Docker Compose 启动本地依赖项（Postgres、Redis 和邮件服务器）——默认使用文件系统存储——请从项目根目录运行以下命令：

docker compose -f hosting/docker/docker-compose.yaml up -d

如果需要在本地使用 S3 兼容后端，请通过 s3 配置文件启用可选的 MinIO 服务：

docker compose -f hosting/docker/docker-compose.yaml --profile s3 up -d

Compose 文件包含一个 server 服务。如果要通过 npm run dev 在本地运行 API，请注释掉（或覆盖）该服务，以便只启动支持服务。

服务器

cd apps/web
npm run dev

桌面端

cd apps/desktop
npm run dev

测试

Colanode 包含服务器和 Web 端的测试。

服务器测试

从 apps/server 目录：

npm run test

服务器测试使用 Testcontainers 来运行 Postgres 和 Redis，因此 Docker 必须处于运行状态。详情请参见 apps/server/README.md。

Web 测试

从 apps/web 目录：

npm run test

许可证

Colanode 基于 Apache 2.0 许可证发布。

---

项目仓库 README（补充）

Colanode

开源且本地优先的协作工作空间，可自行托管

Colanode 是一个一体化协作平台，旨在优先考虑数据隐私和控制权。采用本地优先设计，帮助团队在线或离线状态下进行沟通、组织和管理项目。使用 Colanode，您不仅能获得现代协作工具的灵活性，还能享受数据所有权带来的安心。

Colanode 能做什么？

• 实时聊天：通过团队和个人即时消息保持连接。
• 富文本页面：使用类似 Notion 的直观编辑器创建文档、维基和笔记。
• 可定制数据库：通过结构化数据、自定义字段和动态视图（表格、看板、日历）组织信息。
• 文件管理：在安全工作区内轻松存储、共享和管理文件。

Colanode 适用于个人和团队，无论您是运行小型项目、管理团队还是在整个组织中协作，都能满足您的需求。凭借自托管模式，您可以在享受功能丰富的优质体验的同时，完全控制自己的数据。

工作原理

Colanode 包含客户端应用（Web 或桌面端）和自托管服务器。您可以通过单个应用连接到多个服务器，每个服务器包含一个或多个用于不同团队或项目的工作空间。登录后，您可以选择一个工作空间开始协作——发送消息、编辑页面或更新数据库记录。

本地优先工作流

您所做的所有更改首先保存到本地 SQLite 数据库，然后同步到服务器。后台进程处理同步，因此即使您的计算机或服务器离线，您也可以继续工作。数据读取也在本地进行，确保您能立即访问有权查看的任何内容。

并发编辑

Colanode 依靠无冲突复制数据类型（CRDTs）（由 Yjs 提供支持）来允许对页面或数据库记录等条目进行实时协作。这意味着多人可以同时编辑，系统会优雅地合并所有人的更新。删除操作也作为特殊事务进行跟踪。消息和文件操作不支持并发编辑，使用更简单的数据库表。

免费开始使用

开始使用 Colanode 最简单的方法是通过我们的Web 应用，可立即在 app.colanode.com 访问。只需登录即可立即开始使用，无需任何安装。请注意，Web 应用目前处于早期预览阶段，正在测试中；您可能会在某些浏览器中遇到错误或兼容性问题。

为获得最佳性能，您可以安装我们的桌面应用，可从 下载页面 获取。Web 和桌面应用都允许您连接到我们的任何免费测试版云服务器：

• Colanode Cloud (EU)——托管在欧洲。
• Colanode Cloud (US)——托管在美国。

这两个云服务器目前均处于测试阶段，可免费使用；定价详情即将公布。

自托管

如果您希望托管自己的 Colanode 服务器，请查看 hosting/ 文件夹，其中包含 Docker Compose 文件和部署配置。对于 Kubernetes 部署，请参见 hosting/kubernetes/ 文件夹，其中包含 Helm 图表和其他文档。自行运行 Colanode 需要以下组件：

• 带 pgvector 扩展的 Postgres。
• Redis（任何 Redis 兼容服务均可，例如 Valkey）。
• 用于用户文件的存储后端。Colanode 默认使用本地文件系统存储，但您可以通过设置 STORAGE_TYPE 切换到 S3 兼容、Google Cloud Storage 或 Azure Blob Storage 后端。
• Colanode 服务器 API，以 Docker 镜像形式提供。

配置模型

• 服务器镜像现在附带完整的 config.json，因此大多数默认设置无需修改环境变量即可使用。
• 配置文件是单一事实来源。使用 env://VAR_NAME 从环境变量中提取敏感值，或使用 file://path/to/secret.pem 内联挂载文件的内容（添加 ? 可使两者变为可选）。开箱即用仅需 POSTGRES_URL 和 REDIS_URL。
• 自定义设置方法：

1. 复制 apps/server/config.json，编辑后在使用 Docker Compose 时挂载/绑定（参见 hosting/docker/docker-compose.yaml）。
2. 对于 Helm，启用 colanode.configFile.enabled 并通过 --set-file colanode.configFile.data=./config.json 传递您的文件（详情参见 hosting/kubernetes/README.md）。
3. 将密钥保留为环境变量，这样就不必将它们嵌入 JSON 中；加载器在运行时解析 env:// 指针。

环境变量不再覆盖常规配置字段——只有显式标记为 env:// 的值才会从环境中读取。有关挂载说明和少数必需密钥，请参考 hosting/docker/docker-compose.yaml 和 hosting/kubernetes/README.md。

本地运行

要在开发模式下本地运行 Colanode：

1. 克隆仓库：

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

2. 在项目根目录安装依赖：

npm install

3. 启动要在本地运行的应用：

服务器

cd apps/server

# 复制环境变量模板并根据需要调整值
cp .env.example .env

npm run dev

要使用 Docker Compose 启动本地依赖项（Postgres、Redis 和邮件服务器）——默认使用文件系统存储——请从项目根目录运行以下命令：

docker compose -f hosting/docker/docker-compose.yaml up -d

当偏好本地使用S3兼容后端时，可使用s3配置文件启用可选的MinIO服务：

docker compose -f hosting/docker/docker-compose.yaml --profile s3 up -d

该compose文件包含一个server服务。当您希望通过npm run dev在本地运行API时，请注释掉（或覆盖）该服务，以便只启动支持服务。

Web

cd apps/web
npm run dev

桌面端

cd apps/desktop
npm run dev

测试

Colanode包含服务器和Web端的测试。

服务器测试

在apps/server目录下：

npm run test

服务器测试使用Testcontainers来运行Postgres和Redis，因此Docker必须处于运行状态。详情请参见apps/server/README.md。

Web端测试

在apps/web目录下：

npm run test

许可证

Colanode根据Apache 2.0许可证发布。