Linux安装配置Appwrite平台教程

本文详细介绍了在Linux系统上快速、安全部署Appwrite开源后端平台的完整流程：从一行Docker命令初始化安装，到规避端口冲突、配置Nginx反向代理实现HTTPS域名访问，再到关键的持久化数据管理与平滑升级策略，同时深入揭示了权限设置、网络映射、WebSocket支持、缓存控制及队列服务扩容等易被忽视却直接影响平台稳定性与功能完整性的实操要点——无论你是全栈开发者还是运维工程师，都能据此避开踩坑，高效搭建出生产就绪的现代化后端基础设施。

Linux 上安装 Appwrite 不需要编译源码，也不依赖系统级 Web 服务器（如 Apache 或 Nginx），它完全基于 Docker 容器运行。只要你的 Linux 发行版满足最低要求（Docker 20.10+、2GB 内存、x86_64 架构），一行命令就能完成初始化安装 —— 但后续配置端口、域名、反向代理和持久化路径时，容易因忽略权限或网络映射规则导致控制台打不开或 API 无法访问。

确认 Docker 环境并拉取安装工具

Appwrite 的安装不是直接 docker run 启动服务容器，而是先用官方镜像执行内置的 install 入口脚本，该脚本会自动下载所有微服务镜像、生成配置、初始化数据库，并写入本地 appwrite/ 目录。必须确保：

• Docker daemon 正在运行：sudo systemctl is-active docker 返回 active
• 当前用户在 docker 用户组中，否则 /var/run/docker.sock 会权限拒绝
• $(pwd)/appwrite 路径有读写权限（推荐新建空目录并 chmod 755）

执行安装命令（以最新稳定版为例）：

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.6.0

该命令不会后台运行，而是交互式引导你输入 HTTP 端口（默认 80）、HTTPS 端口（默认 443）、API 密钥、主机名等。若宿主机 80/443 已被占用（比如跑着 Apache 或 CyberPanel），必须改用其他端口，例如 3700 和 3443，否则安装会卡住或后续无法访问。

修改默认端口与绑定地址避免冲突

Appwrite 默认监听 0.0.0.0:80 和 0.0.0.0:443，但在生产环境或已有 Web 服务的机器上，直接暴露这两个端口既不安全也不现实。安装完成后，不能靠改 docker-compose.yml 临时覆盖 —— 因为安装脚本已把端口写死进 appwrite/.env 和生成的 compose 文件里。

正确做法是：进入 appwrite/ 目录，编辑 .env，找到并修改以下两项：

• APPWRITE_HTTP_PORT=3700（对应你安装时填的 HTTP 端口）
• APPWRITE_HTTPS_PORT=3443（对应你安装时填的 HTTPS 端口）

然后重新 up 服务：docker-compose -f docker-compose.yml up -d。注意：不要删掉 appwrite/ 下的 docker-compose.yml，它是安装过程动态生成的，含服务依赖顺序和卷挂载路径，手动重写极易出错。

用 Nginx 反向代理实现域名 + HTTPS 访问

Appwrite 自带的 HTTPS 支持需手动配置证书路径，且重启后易丢失；更稳妥的方式是用 Nginx 做前端反代，由 Nginx 终止 SSL，再以 HTTP 转发到 Appwrite 容器的 3700 端口。关键点在于：

• 代理头必须透传：X-Forwarded-For、X-Forwarded-Proto、X-Forwarded-Host 缺一不可，否则控制台登录页会跳转错误 URL
• WebSocket 路径（/v1/realtime）需显式启用 proxy_http_version 1.1 和 Upgrade 头，否则实时功能失效
• 静态资源缓存要禁用（add_header Cache-Control "no-store, no-cache"），避免 JS/CSS 更新后页面白屏

示例 Nginx server 块片段（替换 your-domain.com）：

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
<pre class="brush:php;toolbar:false;">location / {
    proxy_pass http://127.0.0.1:3700;
    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_set_header X-Forwarded-Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_http_version 1.1;
    add_header Cache-Control "no-store, no-cache";
}

}

持久化数据与升级注意事项

Appwrite 的所有状态（数据库、文件存储、日志）都通过 Docker 卷保存在 appwrite/ 目录下。这意味着：

• 升级版本时，**不能直接改 docker-compose.yml 中的镜像 tag 后 docker-compose up -d** —— 这会导致新旧版本数据库结构不兼容，服务启动失败
• 必须使用官方升级流程：先备份 appwrite/ 目录，再运行新版 install 命令（指定同一 $(pwd)/appwrite 路径），它会检测现有配置并迁移
• 若启用了 S3 兼容存储（如 MinIO），APPWRITE_STORAGE_S3_BUCKET 等变量必须保持一致，否则上传的文件会“消失”

真正容易被忽略的是：Appwrite 的 queue-worker 容器默认只启一个实例，高并发场景下任务堆积会导致邮件发送延迟、函数触发失败。需要手动编辑 docker-compose.yml，将 queue-worker 的 deploy.replicas 改为 2 或 3，并确保 Redis 容器内存足够（至少 512MB）。

以上就是《Linux安装配置Appwrite平台教程》的详细内容，更多关于Linux的资料请关注golang学习网公众号！