Appwrite 是基于 Docker 的端到端开源后端平台，无需编译源码或依赖 Apache/Nginx，一行命令即可安装；它提供用户认证、数据库、存储、云函数、实时通信等服务，支持快速构建安全可扩展应用。
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，找到并修改以下两项：
Zynq‑7000 / Zynq UltraScale+ 硬件调试技能。适用于 Xilinx Zynq（Cortex‑A9/A53 + FPGA）Linux 环境，调试 I2C、I2S、UART、GPIO 等外设。包括设备树配置、内核驱动、用户空间调试工具、交叉编译和常见问题排查，支持 PetaLinux 开发。
-
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）。
