AFFiNE开源工作空间工具本地部署与优化指南

1. 项目概述：AFFiNE 工作空间工具的核心价值

AFFiNE 是新一代开源工作空间工具，它巧妙融合了文档编辑、白板协作和数据库管理三大核心功能。不同于传统办公软件，AFFiNE 采用块编辑器（Block Editor）架构，每个内容单元都是可自由拖拽的独立模块，这种设计让知识管理变得像搭积木一样直观。我在实际部署使用中发现，它的双向链接和跨文档引用功能特别适合处理复杂项目中的知识关联。

作为完全开源的项目，AFFiNE 允许用户自主掌控数据，这对于注重隐私的企业和个人开发者至关重要。最新稳定版已支持实时协作，团队成员可以像使用Notion一样协同编辑，同时又保持了本地优先（Local-first）的设计哲学——所有数据默认存储在用户本地设备，仅在需要时才同步到云端。

2. 本地部署前的环境准备

2.1 硬件与系统要求

实测表明，AFFiNE 对硬件要求较为亲民。我的测试环境是一台配备Intel i5-8250U处理器、8GB内存的普通笔记本，运行Ubuntu 22.04 LTS系统，部署过程十分顺畅。官方推荐的最低配置为：

• CPU：x86_64架构，至少2核
• 内存：4GB（团队协作建议8GB以上）
• 存储：至少2GB可用空间

特别注意：ARM架构设备（如树莓派）需要额外配置，本文以x86_64架构为例。

2.2 依赖环境安装

AFFiNE 后端基于Node.js开发，前端使用Rust构建，因此需要确保系统已安装以下依赖：

bash复制# Ubuntu/Debian系统
sudo apt update
sudo apt install -y git curl build-essential pkg-config libssl-dev

# 安装Node.js 18.x（LTS版本）
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# 验证安装
node -v  # 应显示v18.x
npm -v   # 应显示9.x

对于Windows用户，建议使用WSL2环境部署，可以获得接近Linux原生的性能体验。我在Windows 11 + WSL2(Ubuntu 20.04)环境下测试，整体运行效率比纯Windows环境高出约30%。

3. AFFiNE 的本地部署详解

3.1 源码获取与构建

官方提供多种安装方式，我推荐从源码构建以获得最大灵活性：

bash复制# 克隆仓库（国内用户可使用镜像源加速）
git clone https://github.com/toeverything/AFFiNE.git --depth=1
cd AFFiNE

# 安装依赖（首次运行耗时较长）
npm install -g pnpm
pnpm install
pnpm build

构建过程中常见两个问题：

1. Rust编译卡顿：这是因为首次需要下载Rust工具链，可通过设置国内镜像加速：

   bash复制export RUSTUP_DIST_SERVER=https://rsproxy.cn
   export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup
   

2. 内存不足：在低配设备上可能触发OOM，可增加swap空间：

   bash复制sudo fallocate -l 2G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile
   

3.2 服务启动与初始化

构建完成后，启动开发服务器：

bash复制pnpm start

默认会启动三个服务：

• 前端服务（localhost:3000）
• 后端API服务（localhost:3010）
• WebSocket实时协作服务（localhost:3020）

首次访问http://localhost:3000 会进入初始化向导。这里有个实用技巧：在团队部署时，可以先在本地完成工作区配置，然后导出模板，其他成员导入即可保持配置一致。

4. 实现外部访问的关键配置

4.1 反向代理设置

要使AFFiNE能被外部访问，推荐使用Nginx作为反向代理。以下是我的生产环境配置：

nginx复制server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }

    location /api/ {
        proxy_pass http://localhost:3010/;
        proxy_set_header Host $host;
    }

    location /socket/ {
        proxy_pass http://localhost:3020/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

配置完成后记得测试：

bash复制sudo nginx -t
sudo systemctl restart nginx

4.2 HTTPS安全加固

对外服务必须启用HTTPS，Certbot是免费SSL证书的最佳选择：

bash复制sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

证书自动续期测试：

bash复制sudo certbot renew --dry-run

4.3 防火墙配置

确保防火墙放行必要端口：

bash复制sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

5. 生产环境优化实践

5.1 进程守护方案

开发模式下的pnpm start不适合生产环境，推荐使用PM2进行进程管理：

bash复制npm install -g pm2
pm2 start "pnpm start" --name affine
pm2 save
pm2 startup

5.2 数据持久化配置

默认情况下，AFFiNE将数据存储在~/.local/share/affine目录。对于生产环境，建议：

1. 创建专用数据目录：

   bash复制sudo mkdir /var/lib/affine
   sudo chown -R $USER:$USER /var/lib/affine
   

2. 修改启动命令指定存储路径：

   bash复制pm2 start "STORAGE_PATH=/var/lib/affine pnpm start" --name affine
   

5.3 性能调优经验

• 内存优化：Node.js默认内存限制可能不足，可通过以下方式调整：

  bash复制export NODE_OPTIONS="--max-old-space-size=4096"
  

• 数据库缓存：AFFiNE使用SQLite存储元数据，增加缓存能显著提升性能：

  bash复制export SQLITE_CACHE_SIZE=-200000  # 200MB缓存
  

• 定时重启：防止内存泄漏，每天凌晨自动重启：

  bash复制pm2 restart affine --cron "0 3 * * *"
  

6. 常见问题排查手册

6.1 服务启动失败排查

症状：pnpm start后无法访问页面

排查步骤：

1. 检查端口占用：

   bash复制sudo lsof -i :3000
   

2. 查看详细日志：

   bash复制journalctl -u affine --no-pager -n 50
   

3. 常见错误解决：
   • Error: ENOSPC：增加系统文件监控限制

     bash复制echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
     sudo sysctl -p
     

6.2 协作功能异常处理

症状：多人编辑时变更不同步

解决方案：

1. 检查WebSocket连接：

   javascript复制// 浏览器控制台测试
   new WebSocket('ws://your-domain.com/socket').onerror = console.error
   

2. 确保Nginx配置包含：

   nginx复制proxy_read_timeout 86400s;
   proxy_send_timeout 86400s;
   

6.3 数据迁移与备份

建议的备份方案：

bash复制# 每日全量备份
0 2 * * * tar -czf /backups/affine-$(date +\%Y\%m\%d).tar.gz /var/lib/affine

恢复数据时：

bash复制pm2 stop affine
tar -xzf backup.tar.gz -C /
pm2 start affine

7. 进阶配置与扩展

7.1 集成对象存储

对于大型团队，可以将文件存储切换到S3兼容服务：

1. 修改.env配置文件：

   ini复制STORAGE_PROVIDER=s3
   S3_ENDPOINT=your-s3-endpoint
   S3_BUCKET=affine-storage
   S3_ACCESS_KEY=your-key
   S3_SECRET_KEY=your-secret
   

2. 重启服务：

   bash复制pm2 restart affine
   

7.2 单点登录集成

AFFiNE支持OAuth 2.0协议，以GitHub为例：

1. 创建GitHub OAuth应用
2. 配置环境变量：

   ini复制AUTH_PROVIDERS=github
   GITHUB_CLIENT_ID=your-client-id
   GITHUB_CLIENT_SECRET=your-secret
   

3. 重启后登录页将显示GitHub登录选项

7.3 插件系统开发

AFFiNE提供插件API，示例插件目录结构：

code复制affine-plugin/
├── package.json
├── src/
│   ├── index.ts
│   └── styles.css
└── tsconfig.json

核心开发要点：

• 使用registerBlockAPI添加新块类型
• 通过hook系统拦截编辑器事件
• 样式隔离使用Shadow DOM技术

8. 安全加固指南

8.1 基础安全措施

1. 定期更新：

   bash复制cd /path/to/AFFiNE
   git pull
   pnpm install
   pm2 restart affine
   

2. 敏感文件保护：

   bash复制chmod 600 .env
   

3. 禁用调试接口：

   ini复制# .env
   NODE_ENV=production
   

8.2 访问控制策略

1. IP白名单限制（Nginx配置）：

   nginx复制location / {
       allow 192.168.1.0/24;
       deny all;
       # 原有proxy配置...
   }
   

2. 基础认证保护：

   bash复制sudo apt install apache2-utils
   htpasswd -c /etc/nginx/.htpasswd username
   

   然后在Nginx配置中添加：

   nginx复制auth_basic "Restricted Access";
   auth_basic_user_file /etc/nginx/.htpasswd;
   

8.3 监控与告警

推荐配置Prometheus监控：

1. 暴露metrics接口：

   bash复制export METRICS_ENABLED=true
   pm2 restart affine
   

2. Prometheus配置：

   yaml复制scrape_configs:
     - job_name: 'affine'
       static_configs:
         - targets: ['localhost:3010']
   

关键监控指标：

• nodejs_heap_used_bytes：内存使用情况
• http_requests_total：API请求量
• websocket_connections：实时连接数