全书目录

第五十一篇：Appwrite 完全指南 —— 自托管应用服务综合体宇宙

第五十一篇：Appwrite 完全指南 —— 自托管应用服务综合体宇宙

17 分钟 7,633 字 第 932 / 962 个阅读单元

#1. 先把 Appwrite 看成什么

理解 Appwrite，最稳的类比不是“一个 SDK 集合”，而是“你自己拥有地契的一座应用服务综合体”。

这座综合体里，不同楼层各司其职：

  • Auth 是门禁和住户登记中心
  • Databases 是结构化档案馆
  • Storage 是大件仓库
  • Functions 是后勤自动化车间
  • Messaging 是广播中心
  • Realtime 是楼内对讲系统
  • Console / API / SDK 是物业管理台和对外窗口

也就是说，Appwrite 的本质不是“帮你少写几个接口”，而是把一整套应用后端基础设施，做成一个统一的、可托管也可自托管的平台。

text
                ┌───────────────────────────┐
                │       你的应用前端         │
                │ Web / App / SSR / Mobile  │
                └─────────────┬─────────────┘
                              │ SDK / REST / GraphQL / Realtime
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                           Appwrite                              │
│                                                                 │
│  [Auth]      [Databases]      [Storage]      [Functions]        │
│  门禁中心      档案馆            仓库             自动化车间        │
│                                                                 │
│                 [Messaging]      [Realtime]                     │
│                  广播中心          对讲系统                      │
└─────────────────────────────────────────────────────────────────┘

如果把 Firebase 看成“Google 运营的大型连锁商场”，把 Supabase 看成“以 Postgres 为核心的开放式办公园区”，那么 Appwrite 更像“你可以自己经营的一体化商业综合体”。

#2. Appwrite 的 BaaS / 后端平台心智

很多人把 BaaS 理解成“免后端”。这是错的。

更准确的理解是：

  • BaaS 帮你预制一大批通用后端能力
  • 你不必从零写用户系统、文件系统、权限系统、消息系统
  • 但你的业务规则、权限边界、工作流编排，仍然需要你设计

所以 Appwrite 不是在消灭后端，而是在把后端里最重复、最基础、最易出错的那一层平台能力提前造好。

它和“自己写 Node/Java/Go 后端”的区别，不是有没有后端，而是：

  • 传统做法：你自己先搭地基，再盖楼
  • Appwrite：地基、门禁、仓库、广播都已经建好，你重点装修业务层

这就是 Appwrite 作为“后端平台”而不只是“Auth 服务”的价值。

#3. Auth：门禁和身份中心

Auth 解决的是“谁进楼、带什么身份、能去哪里”。

Appwrite 官方文档给出的认证方式很全，包含：

  • 邮箱密码
  • 手机短信
  • Magic URL
  • Email OTP
  • OAuth 2
  • 匿名登录
  • JWT
  • SSR 登录
  • 自定义 Token
  • MFA

关键不是“登录方式多”，而是它把身份和权限体系绑在一起了。用户登录之后，不只是拿到一个 session，还会进入 Appwrite 的权限模型里，后面的表、行、桶、文件、函数执行权限，都能接上这套身份系统。

最重要的工程点有两个：

  • Account API 给前端客户端用，基于用户 session
  • Users API 给服务端管理用，基于 API Key，不受用户资源权限限制，而受 scope 约束

这意味着：

  • 前端适合做“用户以自己身份操作自己的资源”
  • 服务端适合做“系统代表平台做管理动作”

一个最小登录示例：

ts
import { Client, Account, ID } from "appwrite";

const client = new Client()
  .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
  .setProject("<PROJECT_ID>");

const account = new Account(client);

export async function register(email: string, password: string) {
  await account.create({
    userId: ID.unique(),
    email,
    password,
  });

  await account.createEmailPasswordSession({
    email,
    password,
  });

  return account.get();
}

这段代码背后的心智是：先登记住户，再发门禁卡，再读取当前住户信息。

#4. Databases：结构化档案馆

Databases 解决的是“业务数据放哪里、怎么查、谁能看”。

Appwrite 当前文档里已经明确使用 databases / tables / rows 这一套命名。你可以把它理解为：

  • database：一栋楼里的档案总区
  • table：某类档案柜
  • row：一份具体档案

它不是让你直接抱着数据库裸奔，而是通过平台 API 管理结构化数据、查询、关系、事务、分页、批量操作、原子数值更新、离线同步等能力。

最有辨识度的是它的权限模型：

  • 表级权限
  • 行级权限
  • 默认是“授予式”而不是“天然开放式”

也就是说，不给权限，就看不到。

创建一条只允许当前用户读写的私有行：

ts
import { Client, TablesDB, Permission, Role, ID } from "appwrite";

const client = new Client()
  .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
  .setProject("<PROJECT_ID>");

const tablesDB = new TablesDB(client);

async function createPrivatePost(userId: string) {
  return tablesDB.createRow({
    databaseId: "main",
    tableId: "posts",
    rowId: ID.unique(),
    data: {
      title: "Appwrite 心智图",
      authorId: userId,
      status: "draft",
    },
    permissions: [
      Permission.read(Role.user(userId)),
      Permission.update(Role.user(userId)),
      Permission.delete(Role.user(userId)),
    ],
  });
}

这里最值得记住的一句是：Appwrite 的数据库不是单纯存数据，而是把数据和访问边界一起存起来。

#5. Storage：大件仓库

Storage 解决的是“图片、视频、PDF、附件放哪里”。

数据库适合放结构化信息，不适合扛大文件。Storage 就是综合体里的仓库系统。

Appwrite 的 bucket 很像数据库里的 table：

  • bucket 是文件分组
  • file 是具体文件
  • bucket 和 file 都能挂权限
  • bucket 还能配置文件大小、扩展名、压缩、加密等策略

上传一个只允许自己读取的文件：

ts
import { Client, Storage, Permission, Role, ID } from "appwrite";

const client = new Client()
  .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
  .setProject("<PROJECT_ID>");

const storage = new Storage(client);

async function uploadAvatar(file: File, userId: string) {
  return storage.createFile({
    bucketId: "avatars",
    fileId: ID.unique(),
    file,
    permissions: [Permission.read(Role.user(userId))],
  });
}

一个很实用的心智区分：

  • Databases 放“可查询业务事实”
  • Storage 放“不可直接结构化查询的大对象”

不要把图片 base64 塞进表里，也不要把用户昵称存在 Storage 里。

#6. Functions：自动化车间

Functions 是 Appwrite 里最像“你自己写后端代码”的那一层。

它的作用不是替代整个平台，而是补平台的业务差异化部分。比如：

  • 支付回调校验
  • 审核流程
  • 第三方 webhook
  • 定时任务
  • 生成报表
  • 数据聚合
  • 权限升级动作

Appwrite Functions 可以：

  • 按需执行
  • 被平台事件触发
  • 被 cron 调度
  • 用 Git / CLI / 手动包部署

而且函数执行和平台事件天然接得上，这意味着你可以把“楼里的事件”交给“后勤车间”处理。

手动触发函数执行：

ts
import { Client, Functions } from "appwrite";

const client = new Client()
  .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
  .setProject("<PROJECT_ID>");

const functions = new Functions(client);

async function publishPost(postId: string) {
  return functions.createExecution({
    functionId: "publish-post",
    body: JSON.stringify({ postId }),
  });
}

CLI 侧的思路也很直接：

bash
appwrite init functions
appwrite push functions

要点是：Functions 负责特殊业务逻辑，Auth / Databases / Storage 负责通用平台能力。

#7. Messaging：广播中心

这是 Appwrite 很容易被低估的一层。

Messaging 不只是“发通知”，而是把：

  • Email
  • SMS
  • Push

统一成一个消息中心。

但要注意一个非常关键的边界：Appwrite Messaging 更像“广播调度中心”，不是它自己拥有全球邮件服务器、短信运营商和推送基础设施。官方文档明确要求你接入第三方 provider，例如：

  • Push：APNS、FCM
  • Email：Mailgun、SendGrid、SMTP
  • SMS：Twilio、Vonage 等

所以它的价值在于统一编排，而不是替你拥有底层通信网络。

它还有两个核心概念：

  • target：用户可被触达的终端，比如邮箱、手机号、设备
  • topic：广播频道，把一组 target 组织起来
text
用户
 ├─ target: 邮箱A
 ├─ target: 手机号B
 └─ target: iPhone设备C

多个 target  ──订阅──>  topic: "post-updates"
                               │
                               └── message: 邮件 / 短信 / Push

服务端发送邮件示例：

js
const sdk = require("node-appwrite");

const client = new sdk.Client()
  .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
  .setProject("<PROJECT_ID>")
  .setKey(process.env.APPWRITE_API_KEY);

const messaging = new sdk.Messaging(client);

async function sendPublishedEmail(userId) {
  return messaging.createEmail({
    messageId: sdk.ID.unique(),
    subject: "你的内容已发布",
    content: "<h1>发布成功</h1><p>现在可以去查看详情了。</p>",
    users: [userId],
    html: true,
  });
}

如果把 Firebase 的 FCM 看成“推送专线”，那 Appwrite Messaging 更像“统一广播台”。它不只管 push，还把 email、SMS 放进同一套控制面里。

#8. Realtime：楼内对讲系统

虽然这篇重点不是 Realtime，但 Appwrite 的整体心智离不开它。

官方文档明确说明，Appwrite 支持 REST / GraphQL / Realtime 三种接入方式，Realtime 通过 WebSocket 订阅资源变化，而且权限跟着资源权限走。

最直观的用法是：你不轮询，而是订阅变化。

ts
const unsubscribe = client.subscribe(
  [`tablesdb.main.tables.posts.rows.${postId}`],
  (event) => {
    console.log("row changed:", event);
  }
);

要牢记一个细节：如果用户是“订阅后才登录”，需要重新订阅。因为 Realtime 使用现有 session 做认证，session 变了，订阅关系也要重建。

#9. 一条完整业务链怎么串起来

以“内容发布系统”为例，Appwrite 的协作方式可以这样看：

text
1. 用户注册登录
   Auth 发 session

2. 用户创建帖子
   Databases 写入 row，并附上行级权限

3. 用户上传封面
   Storage 写入 file，并附上文件权限

4. 用户点击发布
   Functions 执行发布逻辑
   ├─ 更新帖子状态
   ├─ 生成摘要/封面处理
   └─ 调用 Messaging

5. 系统通知订阅者
   Messaging 发 email / sms / push

6. 前端页面自动刷新
   Realtime 收到 row / file / execution 变更

这就是 Appwrite 最强的地方：不是单点强，而是整座楼的动线很顺。

#10. 自托管为什么是 Appwrite 的大价值

Appwrite 官方文档对自托管的态度很明确：它从一开始就按自托管设计，可以运行在任何支持 Docker 的系统上；同时也明确提醒，自托管不一定更省钱，时间和运维成本常常更高。

这段话背后的真实含义是：

  • 如果你只是想快，上云托管更省事
  • 如果你想控数据位置、网络边界、合规策略、基础设施细节，自托管才有价值

把“云托管”和“自托管”继续放回综合体类比里：

  • 云托管：你租现成商场铺位
  • 自托管：你自己持有地契、物业、电力、安保、仓储系统

Appwrite 自托管适合这些场景：

  • 数据必须放在指定地区或内网
  • 希望在本地开发环境跑完整后端
  • 团队有基础 DevOps 能力
  • 需要自定义存储、网络、备份、监控策略

官方安装文档给出的最低门槛并不夸张，但也不是“零成本玩具”：

  • 2 CPU
  • 4GB RAM
  • 2GB swap
  • Docker
  • Docker Compose v2

自托管后你还要自己负责：

  • 更新
  • 扩缩容
  • TLS
  • 备份
  • 监控
  • 安全加固

仓库层面也更灵活。官方文档说明 Storage 可以接本地存储，也能接 S3、Backblaze、Wasabi 等后端。这意味着你不仅能自己托管 Appwrite，还能自己决定“仓库建在哪”。

#11. 和 Firebase、Supabase 怎么比

先把两句容易说混的话讲清楚。

下面两点属于基于官方产品矩阵和文档边界的工程判断：

  • Firebase 官方文档整体围绕 Google Cloud 托管能力展开，没有提供与 Appwrite / Supabase 同级的官方自托管路径
  • Supabase 官方核心产品矩阵里没有与 Appwrite Messaging 对等的一体化消息中心，工程上通常是 Auth + Database + Storage + Edge Functions + 第三方消息服务

对比表最清楚：

维度 Appwrite Firebase Supabase
核心气质 一体化 BaaS/后端平台 Google 生态里的托管应用平台 Postgres-first 开放后端平台
身份系统 很全，和资源权限强绑定 很成熟，和 Firebase/Google 服务联动强 很强，JWT + RLS 路线清晰
数据库心智 平台化表/行权限模型 Firestore 是 NoSQL 文档数据库 原生 Postgres/SQL/RLS
文件存储 bucket/file + 平台权限 Cloud Storage for Firebase Storage 与 Postgres/RLS 集成
函数 Appwrite Functions，事件/调度/按需执行 Cloud Functions，Google 生态联动极强 Edge Functions，Deno/TypeScript-first
消息能力 内建统一 Messaging，覆盖 Email/SMS/Push FCM 很强，但偏 push；其他渠道更分散 无 Appwrite 式统一消息中心
自托管 官方主线能力 不以自托管为主线 官方提供自托管入口，但社区支持为主
最适合 想要一体化且保留自托管选择 想极快接入 Google 托管生态 想吃满 Postgres、SQL、RLS 红利

怎么选，给一句短判断：

  • 想要“平台一站式 + 自托管备选 + 统一消息中心”，选 Appwrite
  • 想要“托管优先 + Google 生态 + FCM/Functions”，选 Firebase
  • 想要“Postgres 原教旨主义 + SQL/RLS + 开放架构”，选 Supabase

#12. 常见误区

#误区一：Appwrite 就是 Auth 服务

不是。Auth 只是门禁层。真正的价值在于 Auth、数据、文件、函数、消息、实时能力共用同一套平台边界。

#误区二：自托管一定更便宜

不一定。官方文档已经明确提醒，自托管往往会把时间、维护、运维能力成本一起算进去。

#误区三：用了 Appwrite 就完全不用写后端

不对。你只是不用反复造基础设施。复杂业务、第三方集成、风控、编排，仍然要靠 Functions 或外部服务完成。

#误区四：Messaging 等于自带短信和邮件通道

不对。Appwrite 提供统一消息控制面，但底层发送仍依赖第三方 provider。

#误区五：Functions 可以当万能长任务平台

要克制。官方文档写明系统级最大超时是 900 秒。长时批处理、重转码、重 AI 流水线，不应无脑全塞进去。

#误区六：权限默认会自动帮你配好

要分场景。官方文档明确说明：

  • 用 Server SDK 或 Console 创建资源且不显式写权限时，默认没人能访问
  • 用 Client SDK 创建资源且不显式写权限时，默认创建者拿到读改删权限

这条不搞清楚，最容易出现“怎么全看不到”或“怎么比预期开放”的问题。

#13. 适用与不适用

#适用
  • 中小到中大型应用，需要完整后端底座
  • 前端团队想快速拥有后端能力
  • 想做“用户系统 + 数据 + 文件 + 通知 + 自动化”
  • 有合规、内网、数据主权、自定义基础设施诉求
  • 想统一权限模型，而不是每个服务各自一套
#不太适用
  • 团队强依赖原生 SQL 能力、复杂查询、数据库原生生态，且希望数据库就是第一公民
  • 团队完全不想碰运维，却又执着自托管
  • 系统核心是超复杂事件流、队列编排、超长后台任务，Appwrite 只能做其中一层
  • 已经深度绑定 Google Cloud 全家桶，并把 Firebase 用得非常顺

#14. 总结

Appwrite 最值得建立的心智，不是“开箱即用后端”，而是“你可以托管、也可以自己持有的一座应用服务综合体”。

它把身份、数据、文件、函数、消息、实时更新放进同一套平台宇宙里，最大的好处不是某一个功能有多炫，而是这些功能之间的边界天然一致：

  • 用户是谁，用 Auth
  • 能看什么，用 Permissions
  • 数据放哪，用 Databases
  • 文件放哪，用 Storage
  • 业务差异化逻辑放哪，用 Functions
  • 通知怎么发，用 Messaging
  • 状态怎么同步，用 Realtime

如果 Firebase 像一条高速托管通道，Supabase 像一套以 Postgres 为轴心的工程体系，那么 Appwrite 像一座能快速开业、也能自己接管物业的一体化后端综合体。

#官方来源链接清单