feat: 添加数字人对接中转服务 Docker Compose 部署方案

- digital-human: FastAPI 中转服务，连接客户端与 Dify LLM 平台
- Redis: 容器内缓存，支持请求体哈希缓存（300s TTL）
- 支持通过 DH_PORT 自定义宿主机映射端口
- Redis 默认不暴露端口，通过 docker-compose.redis-expose.yml 按需开启
- 显式声明 digital-human-net 网络，容器间通过内部 DNS 互通
- 修复 redis.ConnectionError 导入路径（使用 redis.exceptions）
- Dockerfile pip 安装回退机制，避免镜像源不可用时构建失败
- 新增 .gitignore 防止 .env 密钥泄露

.env.example

@@ -11,6 +11,11 @@ DIFY_URL=https://your-dify-domain.com/v1
 # 例如：app-PDkSHiHZsZIluoZF7N2OlNZM
 DIFY_API_KEY=app-xxxxxxxxxxxxxxxxxxxx
 
-# Redis 配置（可选，有默认值）
-REDIS_HOST=redis
-REDIS_PORT=6379
+# 服务端口（可选，默认为 8000）
+DH_PORT=8000
+
+# Redis 暴露配置（可选，默认为空 = 不暴露）
+# 设置非空值时启用 docker-compose.redis-expose.yml 覆盖配置
+#   示例：REDIS_EXPOSE_PORT=6379
+# 通常不需要设置，Redis 默认仅在容器网络内部可用
+# REDIS_EXPOSE_PORT=6379

.gitignore

@@ -0,0 +1,12 @@
+.env
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+*.log

README.md

@@ -44,8 +44,8 @@ curl -X POST http://localhost:8000/v1/chat/completions \
 
 | 端口 | 服务 | 说明 |
 |:---|:---|:---|
-| 8000 | digital-human | 中转服务，对外暴露 |
-| 6379 | Redis | 仅容器内部使用 |
+| `${DH_PORT:-8000}` | digital-human | 中转服务，对外暴露（可通过 `DH_PORT` 自定义） |
+| — | Redis | **默认不暴露**，仅在 Docker Compose 内部网络互通 |
 
 ## 环境变量
 
@@ -53,8 +53,22 @@ curl -X POST http://localhost:8000/v1/chat/completions \
 |:---|:---|:---|:---|
 | `DIFY_URL` | 是 | - | Dify 服务地址，如 `https://xxx.com/v1` |
 | `DIFY_API_KEY` | 是 | - | Dify API 密钥 |
-| `REDIS_HOST` | 否 | `redis` | Redis 主机（Docker Compose 内部 DNS） |
+| `DH_PORT` | 否 | `8000` | 宿主机映射端口（如设为 `9000` 则访问 `http://IP:9000`） |
+| `REDIS_HOST` | 否 | `redis` | Redis 主机（Docker Compose 内部 DNS，始终有效） |
 | `REDIS_PORT` | 否 | `6379` | Redis 端口 |
+| `REDIS_EXPOSE_PORT` | 否 | 不暴露 | 需要暴露时在 `.env` 中设置（如 `6379`），配合 `docker-compose.redis-expose.yml` 使用 |
+
+## Redis 端口暴露（可选）
+
+默认情况下 Redis **不占用宿主机任何端口**，digital-human 通过 Docker Compose 内部 DNS 直连。如需从宿主机直连 Redis（如本地调试），执行以下命令：
+
+```bash
+# 启动时合并 Redis 暴露配置
+docker compose -f docker-compose.yml -f docker-compose.redis-expose.yml up -d
+
+# 宿主机即可访问
+redis-cli -h localhost -p 6379
+```
 
 ## 生产部署注意事项
 
@@ -67,10 +81,11 @@ curl -X POST http://localhost:8000/v1/chat/completions \
 
 ```
 .
-├── docker-compose.yml    # 容器编排配置
+├── docker-compose.yml              # 主容器编排（Redis 默认内部模式）
+├── docker-compose.redis-expose.yml # Redis 端口暴露扩展（按需合并）
 ├── Dockerfile                      # 应用镜像构建
 ├── digital-human.py                # FastAPI 中转服务源码
 ├── requirements.txt                # Python 依赖
-├── .env.example          # 环境变量示例
+├── .env.example                    # 环境变量模板
 └── README.md                       # 本文件
 ```

docker-compose.redis-expose.yml

@@ -0,0 +1,17 @@
+# ============================================================
+# Redis 端口暴露扩展配置
+#
+# 场景：需要从宿主机直接连接 Redis（如本地调试）时使用。
+#
+# 使用方式（与 docker-compose.yml 合并）：
+#   docker compose -f docker-compose.yml -f docker-compose.redis-expose.yml up -d
+#
+# 注意：日常生产部署不需要此文件，直接运行 docker-compose.yml 即可。
+# ============================================================
+
+services:
+  redis:
+    ports:
+      - "${REDIS_EXPOSE_PORT:-6379}:6379"
+    networks:
+      - digital-human-net

docker-compose.yml

@@ -1,24 +1,29 @@
 # ============================================================
 # 数字人对接中转服务 - docker-compose.yml
 #
+# 环境变量说明（填入 .env）：
+#   DIFY_URL         - Dify 服务地址
+#   DIFY_API_KEY     - Dify API 密钥
+#   DH_PORT          - 宿主机映射端口（默认 8000）
+#   REDIS_EXPOSE     - Redis 是否暴露宿主机端口，默认 false（仅容器内互通）
+#
 # 使用方法：
-#   1. 将 DIFY_URL 和 DIFY_API_KEY 填入 .env 文件
-#   2. 执行: docker compose up -d
-#   3. 验证: curl http://localhost:8000
+#   1. cp .env.example .env，填入 DIFY_URL 和 DIFY_API_KEY
+#   2. docker compose up -d
+#   3. 验证: curl http://localhost:${DH_PORT:-8000}
 # ============================================================
 
 services:
 
   # ── Redis 缓存服务 ──────────────────────────────────────
+  # Redis 仅在容器网络内部可用，digital-human 通过 Docker Compose
+  # 内部 DNS（redis 服务名）直连，宿主机无法直接访问。
   redis:
     image: redis:7-alpine
     container_name: digital-human-redis
     restart: unless-stopped
-    # 生产环境建议取消注释以下 networks 和 ports 配置
-    # networks:
-    #   - digital-human-net
-    # ports:
-    #   - "6379:6379"
+    networks:
+      - digital-human-net
     healthcheck:
       test: ["CMD", "redis-cli", "ping"]
       interval: 10s
@@ -33,30 +38,24 @@ services:
     container_name: digital-human-relay
     restart: unless-stopped
     ports:
-      - "8000:8000"
+      - "${DH_PORT:-8000}:8000"
     environment:
-      # Dify 服务地址，如 https://atwdify.antiwearvalve.com/v1
       DIFY_URL: "${DIFY_URL}"
-      # Dify API 密钥，如 app-PDkSHiHZsZIluoZF7N2OlNZM
       DIFY_API_KEY: "${DIFY_API_KEY}"
-      # Redis 连接地址（服务名方式，Docker Compose 内部 DNS）
       REDIS_HOST: "redis"
       REDIS_PORT: "6379"
     depends_on:
       redis:
         condition: service_healthy
+    networks:
+      - digital-human-net
     healthcheck:
       test: ["CMD", "curl", "-f", "http://localhost:8000/"]
       interval: 30s
       timeout: 10s
       retries: 3
       start_period: 15s
-    # networks:
-    #   - digital-human-net
 
-# ============================================================
-#  网络配置（生产环境取消注释）
-# ============================================================
-# networks:
-#   digital-human-net:
-#     driver: bridge
+networks:
+  digital-human-net:
+    driver: bridge