Appwrite 后端即服务 BaaS 部署教程

Appwrite 是一款开源的后端即服务（Backend as a Service）平台，提供用户认证、数据库、文件存储、云函数、消息推送等完整的后端能力。开发者可以通过 REST API 或各语言 SDK 快速构建 Web 和移动应用的后端，而不必从零搭建后端服务。本文将介绍如何在搬瓦工 VPS 上使用 Docker 部署 Appwrite。部署前请确保已安装好 Docker 和 Docker Compose。

一、系统要求

操作系统：Ubuntu 20.04+ 或 Debian 11+。
内存：至少 2GB，建议 4GB 以上（Appwrite 运行多个微服务容器）。
磁盘：至少 20GB 可用空间。
CPU：至少 2 核心。
域名：建议绑定域名并配置 SSL。

二、使用官方脚本安装

Appwrite 提供了官方安装脚本，这是最推荐的安装方式：

docker run -it --rm \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \
  --entrypoint="install" \
  appwrite/appwrite:1.5

安装脚本会交互式地询问以下配置项：

HTTP 端口：默认 80，如果端口被占用可以修改。
HTTPS 端口：默认 443。
域名：填入你的域名，例如 appwrite.yourdomain.com。

三、手动 Docker Compose 部署

如果你需要更精细的控制，可以手动部署。先创建项目目录：

mkdir -p /opt/appwrite
cd /opt/appwrite

从 Appwrite 官方仓库下载 Compose 文件和环境变量模板：

curl -o docker-compose.yml https://appwrite.io/install/compose
curl -o .env https://appwrite.io/install/env

编辑 .env 文件，配置关键参数：

# 修改以下配置项
_APP_ENV=production
_APP_DOMAIN=appwrite.yourdomain.com
_APP_DOMAIN_TARGET=appwrite.yourdomain.com
_APP_OPENSSL_KEY_V1=your-random-secret-key
_APP_DB_PASS=your-database-password
_APP_REDIS_PASS=your-redis-password

生成随机密钥：

openssl rand -hex 32

四、启动 Appwrite

cd /opt/appwrite
docker compose up -d

Appwrite 会启动多个容器（通常有 15 个以上），包括主应用、数据库 MariaDB、缓存 Redis、任务队列等。查看启动状态：

docker compose ps

首次启动可能需要 2-3 分钟，等待所有容器状态变为 healthy。

五、配置反向代理（可选）

Appwrite 自带 Traefik 反向代理和自动 SSL 证书管理。如果你希望使用自己的 Nginx 反向代理，需要先修改 Appwrite 的端口映射，避免冲突：

# 在 docker-compose.yml 中将 traefik 服务的端口改为非标准端口
ports:
  - "8080:80"
  - "8443:443"

然后配置 Nginx 反向代理：

cat > /etc/nginx/sites-available/appwrite <<'EOF'
server {
    listen 80;
    server_name appwrite.yourdomain.com;

    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
EOF

ln -s /etc/nginx/sites-available/appwrite /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d appwrite.yourdomain.com

六、初始化与使用

在浏览器中访问你的 Appwrite 地址，首次访问会进入注册页面，创建管理员账户。登录控制台后可以：

创建项目：每个项目拥有独立的数据库、认证和存储。
配置认证：支持邮箱密码、OAuth（GitHub、Google 等）、手机验证码等多种方式。
创建数据库：通过控制台创建集合（Collection）和属性（Attribute），类似 NoSQL 数据库。
文件存储：创建存储桶（Bucket），上传和管理文件。
云函数：支持 Node.js、Python、PHP、Dart 等多种运行时。

七、使用 SDK 连接 Appwrite

以 JavaScript Web SDK 为例，在前端项目中安装并初始化：

# 安装 SDK
npm install appwrite

在代码中初始化客户端：

import { Client, Account, Databases } from 'appwrite';

const client = new Client()
    .setEndpoint('https://appwrite.yourdomain.com/v1')
    .setProject('your-project-id');

const account = new Account(client);
const databases = new Databases(client);

八、数据备份

定期备份 Appwrite 的数据卷：

# 备份 MariaDB 数据库
docker exec appwrite-mariadb mysqldump -u root -p'your_password' --all-databases > /opt/appwrite/backup_db_$(date +%Y%m%d).sql

# 备份上传的文件
tar -czf /opt/appwrite/backup_files_$(date +%Y%m%d).tar.gz /opt/appwrite/uploads/

九、升级 Appwrite

cd /opt/appwrite
docker compose pull
docker compose up -d
# 运行数据库迁移
docker compose exec appwrite migrate

升级前务必做好完整备份，Appwrite 的大版本升级可能包含数据库结构变更。

十、常见问题

容器启动失败

检查日志定位具体问题：

docker compose logs appwrite
docker compose logs appwrite-worker-databases

常见原因包括端口占用、内存不足或 .env 配置错误。

文件上传大小限制

默认文件上传限制为 12MB，可以在 .env 中修改：

_APP_STORAGE_LIMIT=52428800

上面的值为 50MB（以字节为单位）。同时确保 Nginx 的 client_max_body_size 也做了相应调整。

总结

Appwrite 是一个功能完备的自托管 BaaS 平台，能够大幅降低应用开发中后端部分的工作量。在搬瓦工 VPS 上部署 Appwrite 后，你可以快速构建各类 Web 和移动应用的后端服务。由于 Appwrite 运行的容器较多，建议选择内存 2GB 以上的方案。更多教程请参考：Supabase 部署、PocketBase 部署、Docker 安装教程。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的循环折扣。