开发与部署

相关源文件

• .github/actions/setup-node/action.yml
• .vscode/launch.template.json
• .vscode/settings.template.json
• docs/BUILDING.md
• docs/building-desktop-client-app.md
• docs/contributing/assets/release-action.png
• docs/contributing/releases.md
• docs/contributing/tutorial.md

本文档提供了设置开发环境、构建、测试和部署 AFFiNE 应用程序的技术指南。它涵盖了先决条件、Web 和桌面应用程序的构建过程、CI/CD 管道以及部署选项。

有关 AFFiNE 特定架构方面的信息，请参阅架构概述。有关 monorepo 结构详情，请参阅Monorepo 结构。

开发环境设置

AFFiNE 需要 Node.js 和 Rust 工具链才能成功构建。以下概述了设置开发环境所需的步骤。

先决条件

Node.js 安装

AFFiNE 需要 Node.js LTS 版本（目前为 20.x）。您可以：

1. 从官方网站手动安装 Node.js
2. 使用 node 版本管理器，例如fnm

Rust 安装

请遵循官方指南安装 Rust 工具链。

Yarn 设置

AFFiNE 使用现代 Yarn (4.x)。如果您有 Yarn 1.x，请运行

仓库设置

克隆仓库

Windows 注意：Windows 需要管理员权限才能创建符号链接。请启用开发者模式或以管理员权限执行以下命令

来源：docs/BUILDING.md18-82 docs/building-desktop-client-app.md35-37

安装依赖项

克隆存储库后，安装依赖项

构建原生依赖项

AFFiNE 通过 NAPI.rs 使用用 Rust 编写的原生模块。构建原生模块

注意：在 macOS 上，请使用系统strip工具，而不是binutils。

构建服务器依赖项

如果您正在处理服务器组件

来源：docs/BUILDING.md84-97

开发工作流

启动开发服务器

启动 Web 应用程序的开发服务器

对于 AFFiNE Cloud（后端服务器）

调试

AFFiNE 包含用于调试的 VSCode 启动配置。复制模板文件

这将提供以下调试配置

• 启动 AFFiNE Cloud：以调试模式启动后端服务器
• 启动 AFFiNE Web：以调试模式启动 Web 应用程序
• 调试 AFFiNE Web：使用 Chrome 调试器附加到 Web 应用程序

来源：.vscode/launch.template.json1-35 docs/contributing/tutorial.md45-56

构建 AFFiNE

AFFiNE 可以针对包括 Web 和桌面应用程序在内的各种目标进行构建。构建过程因目标而异。

构建 Web 应用程序

Web 应用程序是 AFFiNE 的核心，也是桌面构建所必需的。在安装依赖项和构建原生模块后

这将使用生产配置构建 Web 应用程序。

来源：docs/BUILDING.md99-120

构建桌面应用程序

构建桌面应用程序更复杂，因为它使用 Electron 包装预构建的 Web 应用并包含原生模块。

第一步：生成资源

首先，构建核心应用程序

第二步：为桌面构建重新配置 Yarn

Electron builder 对 node_modules 结构有特定要求

然后清理所有 node_modules 并重新安装

第三步：构建安装程序

适用于 Mac 和 Linux

适用于 Windows（提供两种安装程序选项）

构建好的安装程序将位于packages/frontend/electron/out/make。

来源：docs/building-desktop-client-app.md38-116

测试

AFFiNE 使用 Playwright 进行端到端测试，使用 vitest 进行单元测试。

单元测试

使用以下命令运行单元测试

端到端测试

对于端到端测试，首先确保已安装浏览器二进制文件

然后运行端到端测试

提供各种端到端测试套件

• affine-local：本地功能测试
• affine-migration：数据迁移测试
• affine-prototype：原型功能测试

来源：docs/BUILDING.md100-120

CI/CD 流水线

AFFiNE 使用 GitHub Actions 进行持续集成和部署。CI/CD 管道自动化应用程序的测试、构建和发布。

Node.js 设置 Action

AFFiNE 使用自定义的 GitHub Action 来设置 Node.js，该 Action 包括缓存配置以提高性能。此 Action 定义在.github/actions/setup-node/action.yml，并管理

• Node.js 的正确版本安装
• Yarn 配置
• node_modules 的缓存
• Playwright 浏览器的缓存
• Electron 二进制文件的缓存

CI 过程中使用的关键环境变量

环境变量	目的
BUILD_TYPE	指定构建类型（canary、beta、stable）
SKIP_WEB_BUILD	构建桌面应用程序时跳过 Web 应用程序的重新构建
HOIST_NODE_MODULES	控制 Electron 构建的 node_modules 的提升
ELECTRON_SKIP_BINARY_DOWNLOAD	防止重复下载 Electron
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD	防止重复下载 Playwright 浏览器

来源：.github/actions/setup-node/action.yml1-213

发布流程

发布过程通过专用的 GitHub 工作流进行管理，该工作流为所有支持的平台构建应用程序并将构建产物上传到 GitHub Releases。

谁可以进行发布

AFFiNE 核心团队授予已获得以下权限的团队成员发布授权

• 对 AFFiNE 存储库的提交访问权限
• GitHub Actions 的访问权限

进行发布

1. 更新package.json中的版本

2. 提交更改并推送到canary分支

3. 在Release Desktop App 工作流中触发发布操作。

4. 工作流完成后，编辑 GitHub Releases 页面的草稿版本并发布。

来源：docs/contributing/releases.md1-49 docs/building-desktop-client-app.md118-122

部署

AFFiNE 可以在各种环境（包括云托管和自托管）中进行部署。

自托管指南

AFFiNE 可以通过以下步骤进行自托管

1. 按照上述构建说明构建应用程序
2. 启动服务器

服务器默认可在http://:3000访问。

Docker 部署

AFFiNE 也可以使用 Docker 进行部署。Docker 镜像作为 CI/CD 管道的一部分进行构建，并发布到 GitHub Container Registry。

运行 Docker 镜像

环境配置

AFFiNE 服务器支持各种环境变量进行配置

环境变量	描述	默认
PORT	服务器端口	3000
DATABASE_URL	数据库连接字符串	sqlite:affine.db
STORAGE_TYPE	存储类型（local、r2）	本地
LOCAL_STORAGE_PATH	本地存储路径	./storage
R2_ACCOUNT_ID	Cloudflare R2 账户 ID	-
R2_ACCESS_KEY_ID	Cloudflare R2 访问密钥 ID	-
R2_SECRET_ACCESS_KEY	Cloudflare R2 秘密访问密钥	-
R2_BUCKET_NAME	Cloudflare R2 存储桶名称	-

来源：.vscode/settings.template.json33-35

常见问题排查

Windows 符号链接

在 Windows 上，符号链接需要开发者模式或管理员权限。如果遇到与符号链接相关的错误

1. 启用开发者模式（Windows 设置 > 更新和安全 > 开发者）
2. 以管理员权限运行 Git 命令
3. 确保 Git 配置中的core.symlinks设置为true

原生模块构建失败

如果您在构建原生模块时遇到问题

1. 确保 Rust 工具链已正确安装
2. 检查是否使用了正确的 Node.js 版本
3. 在 macOS 上，请使用系统strip工具，而不是binutils
4. 清除 node_modules 并重新安装依赖项

Electron 构建问题

由于打包的复杂性，Electron 构建可能很棘手。常见解决方案：

1. 确保您已按照重新配置 Yarn 的确切步骤操作
2. 如果您不进行代码签名，请在forge.config.js中注释掉osxSign和osxNotarize
3. 确保在构建之前已运行 generate-assets 步骤

来源：docs/building-desktop-client-app.md90-91