AFFiNE后端开发环境搭建

环境参数

◇ 我是在 Windows 上搭建的，以下版本号信息供参考，非必须完全一致。

Name	version
Win11	24H2
Docker Desktop	v4.40.0
rustc	1.86.0
node	v20.19.0
PostgreSQL	17.4
Redis	7.4.3
AFFiNE	canary: 7e4af90c0311e498f5119b034397b5ae8a7af9ec

操作步骤

◆ 在 AFFiNE 项目根目录执行 yarn install 成功安装所有依赖。
◆ 后端项目是其中的 @affine/server 子项目。
◆ 安装 Docker Desktop 与 Rust。
◆ 使用 docker 运行 Redis，docker-compose.yaml 内容如下：

services:
  affine-redis:
    image: redis:latest
    container_name: affine-redis
    restart: always
    ports:
      - "6379:6379"

◆ 使用 docker 运行 PostgreSQL，docker-compose.yaml 内容如下。
（1）由于 Postgres 要求挂载目录支持硬链接（hard link），Windows 上不能使用本地磁盘目录。于是使用让 docker 创建的名为"affine_pgdata"的 volume 做数据持久化。

services:
  affine-postgres:
    image: postgres:latest
    container_name: affine-postgres
    restart: always
    ports:
      - "5432:5432"
    volumes:
      - affine_pgdata:/var/lib/postgresql/data
volumes:
  affine_pgdata:

◆ 在数据库中创建项目所使用的用户名、密码与数据库实例。

# 进入数据库容器的数据库命令行
docker exec -it affine-postgres psql -U postgres

# 创建项目用户
CREATE USER affine WITH PASSWORD 'affine';
ALTER USER affine WITH SUPERUSER;

# 创建数据库
CREATE DATABASE affine;

◆ 我使用开发环境下会自动创建的用户调试(packages\backend\server\src\core\auth\dev.ts\createDevUsers())，所以未启动 mailhog 服务也未在下一步配置 mail 相关字段。

◆ 项目数据库连接配置，进入项目 packages\backend\server 路径，参考".env.example"创建配置文件".env"，文件内容如下。

1	DATABASE_URL="postgres://affine:affine@localhost:5432/affine"

◆ 使用项目所依赖的 prisma 创建项目数据库表，在项目根目录执行：

1	yarn workspace @affine/server prisma db push

◆ 如果上步执行报错：Could not open extension control file "/usr/share/postgresql/17/extension/vector.control": No such file or directory。则执行以下步骤后重新执行上步命令。

# 进入数据库容器的bash命令行
docker exec -it affine-postgres /bin/bash

# 更新apt-get工具
apt-get update

# 安装缺少的vector扩展，其中的"17"与报错信息里的一致
apt-get install postgresql-17-pgvector

◆ 初始化数据库中的项目数据。在项目根目录执行下面命令，注意要带上"run"，不然所执行的"yarn init"就是 yarn 自带的 init 命令了。

1	yarn workspace @affine/server run init

◆ 编译 @affine/server 所依赖的 @affine/server-native。执行下面命令，此时会用到 Rust 环境。

1	yarn workspace @affine/server-native build:debug

◆ 如果上步执行报错：'cargo' 不是内部或外部命令，也不是可运行的程序。则执行以下步骤后重新执行上步命令。
（1）确认 Rust 已安装，powershell 和 cmd 中 cargo --version 打印正常。
（2）终端正常启动时会加载用户级+系统级的 PATH 变量，确认环境变量的 PATH 中存在"C:\Users\用户名\.cargo\bin"。
（3）在报错位置"node_modules\@napi-rs\cli\dist\utils\metadata.js"，增加 console.log(process.env.PATH)打印，看其中是否没有"C:\Users\用户名\.cargo\bin"。原因很可能是在安装完 Rust 后的广播 PATH 变更环节异常，重启电脑可解决。

◆ 启动后端。在项目根目录执行 yarn dev，选择"@affine/server"。

admin 管理页面

△ 以 self-hosted 模式部署的 AFFiNE 可以通过 http://locahost:3010/admin 访问 admin 管理页面。本地开发环境需要做下面两步操作才可以。

self-hosted 模式

□ 在.env 文件中追加 DEPLOYMENT_TYPE 字段。

1	DEPLOYMENT_TYPE="selfhosted"

admin 页面资源

○ 编译 @affine/admin。项目根目录执行：

1	yarn affine @affine/admin build

○ 拷贝 packages\frontend\admin\dist 下的所有内容到 packages\backend\server\static\admin

参考文献

●官方 Doc 网站-Node Dev Guide
●self-hosted 模式 AFFiNE 的部署