从零开始自建开源协作平台：AppFlowy Cloud部署全指南

在数据隐私日益重要的今天，越来越多的团队和个人开始寻求能够完全掌控数据的协作解决方案。AppFlowy Cloud作为一款开源的Notion替代方案，提供了数据自主控制、完全开源、强大协作功能等核心优势，让你能够在自己的服务器上搭建安全可控的协作平台。本文将带你一步步完成AppFlowy Cloud的部署过程，从环境准备到安全配置，再到不同场景的优化，让你轻松拥有属于自己的协作空间。

为什么选择自建AppFlowy Cloud？

AppFlowy Cloud是一个基于Flutter和Rust构建的开源协作平台，它与传统的云端协作工具相比，具有以下显著优势：

• 数据自主控制：所有数据存储在你自己的服务器上，无需担心第三方数据泄露或服务终止
• 完全开源：基于Apache 2.0许可证，代码透明可审计，你可以根据需求自由修改和定制
• 跨平台支持：无缝支持Web、桌面和移动端，随时随地访问你的工作空间
• 企业级安全：支持OAuth、SSO等多种认证方案，满足团队和企业的安全需求
• 高性能：采用Rust后端和Flutter前端，提供流畅的实时协作体验

部署前的环境准备

在开始部署AppFlowy Cloud之前，请确保你的环境满足以下要求：

系统要求

组件	最低要求	推荐配置
操作系统	Linux/macOS/Windows	Ubuntu 20.04 LTS
内存	2GB RAM	4GB RAM
存储空间	10GB 可用空间	20GB SSD
Docker	Docker 20.10+	Docker 24.0+
Docker Compose	Docker Compose v2+	Docker Compose v2.20+

网络要求

• 服务器需要能够访问互联网以下载必要的依赖和镜像
• 开放必要的端口：80（HTTP）、443（HTTPS）、22（SSH，可选）

AppFlowy Cloud架构解析

在开始部署前，让我们先了解一下AppFlowy Cloud的架构，这将帮助你更好地理解后续的配置过程。

AppFlowy Cloud采用Docker容器化部署，主要包含以下组件：

• Nginx：作为反向代理，处理HTTP请求路由
• AppFlowy-Cloud：核心应用服务，提供协作功能
• GoTrue：身份认证服务，处理用户登录和授权
• PostgreSQL：关系型数据库，存储用户和工作区数据
• Redis：缓存服务，支持实时协作功能
• MinIO：对象存储服务，存储上传的文件和附件
• PgAdmin：PostgreSQL数据库管理工具
• Portainer：Docker容器管理工具

这些组件通过Docker Compose编排，形成一个完整的协作平台生态系统。

step-by-step部署指南

1. 获取源代码

首先，克隆AppFlowy Cloud的源代码到你的服务器：

# 克隆项目仓库
git clone https://gitcode.com/GitHub_Trending/ap/AppFlowy-Cloud
cd AppFlowy-Cloud

2. 环境配置

复制环境配置文件并进行必要的修改：

# 复制示例配置文件
cp env.dev.secret.example env.dev.secret

# 使用文本编辑器编辑配置文件
nano env.dev.secret

在配置文件中，你需要至少设置以下关键参数：

参数	说明	示例值
DATABASE_URL	PostgreSQL数据库连接URL	postgres://user:password@postgres:5432/appflowy
REDIS_URL	Redis连接URL	redis://redis:6379
APPFLOWY_CLOUD_URL	应用访问URL	http://your-domain.com
JWT_SECRET	JWT令牌加密密钥	随机生成的32位字符串

3. 服务器安全配置

为了确保服务器安全，需要正确配置网络安全组规则。以下是在AWS EC2实例上配置安全组的示例：

安全组配置建议：

1. 仅开放必要端口：80（HTTP）、443（HTTPS）、22（SSH，仅限信任IP）
2. 限制SSH访问来源，仅允许特定IP地址连接
3. 禁止直接暴露数据库和Redis端口到公网

记录你的服务器公网IP或域名，后续配置会用到：

4. 配置OAuth认证

AppFlowy Cloud支持多种OAuth提供商，这里以Google OAuth为例进行配置：

4.1 创建Google OAuth凭据

1. 访问Google Cloud控制台
2. 创建新项目或选择现有项目
3. 在"API和服务" > "凭据"页面，点击"创建凭据"：

4. 选择"OAuth客户端ID"，应用类型选择"Web应用"
5. 填写应用名称，添加授权重定向URL：http://your-domain.com:9998/callback

6. 记录生成的客户端ID和客户端密钥

4.2 配置环境变量

编辑环境配置文件，添加Google OAuth相关设置：

nano env.dev.secret

添加以下配置：

# Google OAuth2
GOTRUE_EXTERNAL_GOOGLE_ENABLED=true
GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID=你的客户端ID
GOTRUE_EXTERNAL_GOOGLE_SECRET=你的客户端密钥
GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI=http://your-domain.com:9998/callback

5. 启动服务

使用Docker Compose启动所有服务：

# 后台启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

预期输出应显示所有服务状态为"Up"：

      Name                    Command               State           Ports         
----------------------------------------------------------------------------------
appflowy-cloud        /appflowy-cloud              Up      0.0.0.0:8080->8080/tcp
gotrue                /gotrue                      Up      0.0.0.0:9998->9998/tcp
minio                 /usr/bin/docker-entrypoint    Up      0.0.0.0:9000->9000/tcp
nginx                 /docker-entrypoint.sh ngin... Up      0.0.0.0:80->80/tcp   
pgadmin               /entrypoint.sh                Up      0.0.0.0:5050->5050/tcp
postgres              docker-entrypoint.sh postgres Up      0.0.0.0:5432->5432/tcp
redis                 docker-entrypoint.sh redis... Up      0.0.0.0:6379->6379/tcp
portainer             /portainer                    Up      0.0.0.0:9001->9000/tcp

6. 验证部署

1. 打开浏览器，访问你的服务器IP或域名
2. 应该能看到AppFlowy Cloud的登录页面
3. 使用Google账号登录，验证OAuth配置是否正确
4. 创建工作区并测试基本功能

高级配置：企业级SSO集成

对于企业用户，AppFlowy Cloud支持SSO集成，以Okta SAML为例：

1. 在Okta中创建应用集成

1. 登录Okta管理控制台
2. 进入"应用程序"页面，点击"创建应用集成"：

3. 选择"SAML 2.0"作为集成方法
4. 填写应用名称，点击"下一步"

2. 配置SAML设置

在SAML配置页面，设置以下参数：

• 单一登录URL：https://your-domain.com/gotrue/sso/saml/acs
• 受众URI(SP实体ID)：https://your-domain.com/gotrue/sso/saml/metadata
• 属性语句：添加email属性，值为user.email

完成配置后，下载IdP元数据，然后在AppFlowy Cloud中配置SAML认证。

常见场景配置

个人使用场景

对于个人用户，推荐以下配置：

1. 简化安全组配置，只开放必要端口
2. 使用自签名SSL证书（生产环境建议使用Let's Encrypt）
3. 定期备份PostgreSQL数据库：

# 创建数据库备份脚本
nano backup_db.sh

添加以下内容：

#!/bin/bash
BACKUP_DIR="/path/to/backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
docker exec appflowy-cloud_postgres_1 pg_dump -U postgres appflowy > $BACKUP_DIR/appflowy_$TIMESTAMP.sql
# 保留最近30天的备份
find $BACKUP_DIR -name "appflowy_*.sql" -mtime +30 -delete

添加执行权限并设置定时任务：

chmod +x backup_db.sh
crontab -e
# 添加以下行，每天凌晨3点执行备份
0 3 * * * /path/to/backup_db.sh

团队协作场景

对于团队使用，建议额外配置：

1. 启用SSO认证，集中管理用户
2. 配置邮件通知服务，用于用户邀请和密码重置
3. 设置资源使用限制，防止单个用户过度占用存储空间

企业部署场景

企业级部署需要更严格的安全和管理配置：

1. 使用企业级SSL证书，确保通信安全
2. 配置LDAP/Active Directory集成，与企业现有用户系统对接
3. 设置详细的审计日志，跟踪用户操作
4. 实现高可用部署，确保服务稳定性

监控与维护

健康检查

使用项目提供的健康检查脚本：

# 执行健康检查
./script/lib/check_health.sh

日志监控

查看服务日志：

# 查看AppFlowy Cloud服务日志
docker-compose logs -f appflowy-cloud

# 查看Nginx访问日志
docker-compose logs -f nginx

性能监控

使用Portainer监控容器资源使用情况：

1. 访问http://your-domain.com:9001
2. 创建管理员账号
3. 查看各容器的CPU、内存和网络使用情况

故障排除

常见问题及解决方案

1. 数据库连接失败

   • 检查DATABASE_URL配置是否正确
   • 确认PostgreSQL容器是否正常运行：docker-compose ps postgres
   • 查看数据库日志：docker-compose logs postgres

2. OAuth认证失败

   • 验证回调URL是否与OAuth提供商配置一致
   • 检查客户端ID和密钥是否正确
   • 查看Gotrue服务日志：docker-compose logs gotrue

3. 服务无法访问

   • 检查Nginx容器是否正常运行
   • 验证服务器防火墙规则是否允许80/443端口
   • 查看Nginx日志：docker-compose logs nginx

4. 存储空间不足

   • 清理未使用的Docker镜像：docker system prune -a
   • 检查MinIO存储使用情况：访问http://your-domain.com:9001
   • 考虑配置外部存储服务

总结

通过本文的指南，你已经成功部署了自己的AppFlowy Cloud开源协作平台。从环境准备到安全配置，再到高级功能集成，你现在拥有了一个完全自主可控的协作空间。无论是个人使用、团队协作还是企业部署，AppFlowy Cloud都能满足你的需求，同时保证数据安全和隐私保护。

随着使用的深入，你可以进一步探索AppFlowy Cloud的定制化选项，根据自己的需求扩展功能。作为开源项目，AppFlowy Cloud拥有活跃的社区支持，你可以通过贡献代码或反馈问题来帮助项目不断改进。

现在，开始享受你的自建协作平台吧！