FastAPI与Appwrite的Docker Compose生产/开发环境搭建及连接问题排查

• 容器内部网络的localhost指向FastAPI容器自身，并非宿主机映射的Appwrite端口，直接指向localhost:5000必然触发连接拒绝
• 原有配置中app（FastAPI）服务未加入自定义桥接网络，无法通过Docker内置DNS解析其他服务的IP
• Traefik原有路由规则将所有根路径请求全部分配给Appwrite，未给FastAPI预留独立转发入口，存在路由冲突
• 卷挂载路径与FastAPI官方镜像的默认工作目录不匹配，本地代码无法同步到容器内
• 官方FastAPI镜像默认监听80端口，原有配置中指向3000端口的转发无实际服务响应

修改后完整docker-compose.yml关键段 #

其余原有服务（mariadb/redis/smtp/influxdb/telegraf）配置保持不变，仅替换以下服务段：

version: '3'

services:
    app:
        build: ./app
        restart: unless-stopped
        volumes:
            - ./app:/app # 修正挂载路径，匹配镜像默认工作目录
        environment:
            - PORT=3000 # 强制服务监听3000端口，和预期端口对齐
        networks:
            - gateway
            - appwrite
        labels:
            - traefik.http.routers.fastapi.rule=PathPrefix(`/api`)
            - traefik.http.services.fastapi.loadbalancer.server.port=3000
            - traefik.http.routers.fastapi-secure.rule=PathPrefix(`/api`)
            - traefik.http.routers.fastapi-secure.tls=true

    traefik:
        image: traefik:v2.1.4
        command:
            - --providers.file.directory=/storage/config
            - --providers.file.watch=true
            - --providers.docker=true
            - --providers.docker.exposedbydefault=false # 仅识别带显式标签的服务，避免自动路由冲突
            - --entrypoints.web.address=:80
            - --entrypoints.websecure.address=:443
        restart: unless-stopped
        ports:
            - 5000:80
            - 443:443
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
            - appwrite-config:/storage/config:ro
            - appwrite-certificates:/storage/certificates:ro
        depends_on:
            - appwrite
            - app
        networks:
            - gateway
            - appwrite

    appwrite:
        image: appwrite/appwrite:0.6.2
        restart: unless-stopped
        networks:
            - appwrite
        labels:
            # 排除/api路径的请求，避免和FastAPI路由冲突
            - traefik.http.routers.appwrite.rule=PathPrefix(`/`) && !PathPrefix(`/api`)
            - traefik.http.routers.appwrite-secure.rule=PathPrefix(`/`) && !PathPrefix(`/api`)
            - traefik.http.routers.appwrite-secure.tls=true
        volumes:
            - appwrite-uploads:/storage/uploads:rw
            - appwrite-cache:/storage/cache:rw
            - appwrite-config:/storage/config:rw
            - appwrite-certificates:/storage/certificates:rw
        depends_on:
            - mariadb
            - redis
            - smtp
            - influxdb
            - telegraf
        environment:
            - _APP_ENV=production
            - _APP_OPENSSL_KEY_V1=your-secret-key
            - _APP_DOMAIN=localhost
            - _APP_DOMAIN_TARGET=localhost
            - _APP_REDIS_HOST=redis
            - _APP_REDIS_PORT=6379
            - _APP_DB_HOST=mariadb
            - _APP_DB_PORT=3306
            - _APP_DB_SCHEMA=appwrite
            - _APP_DB_USER=user
            - _APP_DB_PASS=password
            - _APP_INFLUXDB_HOST=influxdb
            - _APP_INFLUXDB_PORT=8086
            - _APP_STATSD_HOST=telegraf
            - _APP_STATSD_PORT=8125
            - _APP_SMTP_HOST=smtp
            - _APP_SMTP_PORT=25

# 以下网络和卷配置保持原有定义不变
networks:
    gateway:
    appwrite:

volumes:
    appwrite-mariadb:
    appwrite-redis:
    appwrite-cache:
    appwrite-uploads:
    appwrite-certificates:
    appwrite-influxdb:
    appwrite-config:

FastAPI代码内Appwrite SDK初始化修改 #

将原有指向localhost:5000的配置替换为Docker内部网络地址，无需经过宿主机端口映射：

from appwrite.client import Client

client = Client()
# 同网络下直接通过服务名解析，走Docker内部桥接网络
client.set_endpoint('http://appwrite/v1')
client.set_project('你的项目ID')
client.set_key('你的项目API密钥')

• 启动服务后进入FastAPI容器内部，执行curl http://appwrite/v1/health，返回正常响应即代表网络连通
• 访问宿主机5000端口，根路径对应Appwrite控制台，/api路径对应FastAPI服务，无路由冲突
• 触发业务逻辑调用Appwrite接口，确认无连接拒绝报错

• Appwrite 0.6.2版本需搭配0.6.x版本的Python SDK，高版本SDK存在接口不兼容问题
• 跨容器服务通信全程走内部Docker网络，无需将Appwrite端口映射到宿主机，减少不必要的端口暴露面
• 开发环境下如需热重载，需确保requirements.txt内的依赖安装在容器内的挂载目录下，避免依赖缺失
• 生产环境部署时需将_APP_DOMAIN替换为实际的访问域名，配置有效的SSL证书，避免硬编码localhost导致的跨域问题

内容的提问来源于stack exchange，提问作者Alin Climente