AFFiNE开源工作空间本地部署与安全访问指南-代码聚汇网

AFFiNE开源工作空间本地部署与安全访问指南

北陌大叔

1. 项目概述

AFFiNE 是一款新兴的开源工作空间工具，它集成了文档编辑、白板协作、任务管理等多种功能于一体。与 Notion 等商业产品不同，AFFiNE 提供了完整的本地部署方案，让用户能够完全掌控自己的数据。最近我在自己的开发环境中部署了 AFFiNE，并实现了从外部网络的安全访问，整个过程遇到不少值得分享的技术细节。

2. 环境准备与部署

2.1 系统要求分析

AFFiNE 对运行环境有一定要求：

操作系统：Linux/Windows/macOS（推荐 Linux）
内存：至少 4GB（8GB 以上更佳）
存储空间：500MB 以上
Node.js 版本：16.x 或更高

注意：生产环境建议使用 Linux 系统，可以获得更好的性能和稳定性。我在 Ubuntu 22.04 LTS 上测试通过。

2.2 安装依赖组件

首先需要安装必要的依赖：

bash复制# Ubuntu/Debian
sudo apt update
sudo apt install -y git curl build-essential

# CentOS/RHEL
sudo yum install -y git curl make gcc-c++

然后安装 Node.js 和 yarn：

bash复制curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt install -y nodejs
sudo npm install -g yarn

2.3 获取 AFFiNE 源代码

从 GitHub 克隆最新代码：

bash复制git clone https://github.com/toeverything/AFFiNE.git
cd AFFiNE

3. 本地部署流程

3.1 构建前端资源

进入项目目录后，首先构建前端：

bash复制cd affine
yarn install
yarn build

这个过程可能会花费 5-10 分钟，取决于机器性能。构建完成后会生成 dist 目录。

3.2 配置后端服务

后端基于 Node.js 运行：

bash复制cd ../server
yarn install

修改配置文件 .env：

env复制NODE_ENV=production
PORT=3000
DATABASE_URL=file:./affine.db

3.3 启动服务

同时启动前后端：

bash复制# 在前端目录
yarn start

# 在新终端进入后端目录
yarn start

服务启动后，默认可以通过 http://localhost:3000 访问。

4. 实现外部访问方案

4.1 反向代理配置

为了安全地暴露服务到公网，我选择了 Nginx 作为反向代理：

nginx复制server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

4.2 HTTPS 加密

使用 Let's Encrypt 获取免费 SSL 证书：

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

4.3 防火墙配置

确保只开放必要的端口：

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

5. 高级配置与优化

5.1 数据库持久化

默认使用的 SQLite 适合开发环境，生产环境建议切换：

env复制DATABASE_URL=postgresql://user:password@localhost:5432/affine

5.2 性能调优

修改 Node.js 内存限制：

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

5.3 自动启动配置

创建 systemd 服务文件 /etc/systemd/system/affine.service：

ini复制[Unit]
Description=AFFiNE Service
After=network.target

[Service]
User=affine
WorkingDirectory=/path/to/AFFiNE/server
ExecStart=/usr/bin/yarn start
Restart=always

[Install]
WantedBy=multi-user.target

6. 常见问题解决

6.1 构建失败处理

如果遇到构建错误，尝试：

bash复制rm -rf node_modules
yarn cache clean
yarn install

6.2 端口冲突

如果 3000 端口被占用，可以修改：

env复制PORT=3001

并相应调整 Nginx 配置。

6.3 内存不足

增加交换空间：

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

7. 安全注意事项

定期备份数据库文件
保持系统和依赖项更新
限制管理后台的访问IP
启用双因素认证（如果支持）
监控异常登录行为

我在实际部署中发现，AFFiNE 虽然功能强大，但在生产环境使用时还需要考虑更多运维方面的细节。特别是数据备份策略，建议至少每天进行一次完整备份。另外，由于是开源项目，关注 GitHub 上的 issue 和更新也很重要，可以及时获取安全补丁和新功能。