AIclinicalresearch/docs/05-部署文档/_archive-2025首次部署/03-Dify-ECS部署完全指南.md

Dify ECS 部署完全指南

文档版本: v1.1 (修复致命配置错误)
创建时间: 2025-12-13
最后修订: 2025-12-13
适用范围: AIclinicalresearch 平台 - Dify RAG 服务部署
目标读者: 运维工程师、后端开发工程师

v1.1 更新日志:

• ✅ 修复：Redis 配置从 localhost 改为 redis（致命错误）
• ✅ 新增：Swap 分区配置步骤（避免 OOM）
• ✅ 修正：强调使用官方 docker-compose.yaml（包含 Nginx 网关）
• ✅ 完善：故障排查章节，新增 Redis 连接失败和 CORS 错误的解决方案

---

📋 文档目录

1. 为什么选择 ECS + Docker Compose
2. 部署架构图
3. 前置准备清单
4. ECS 服务器配置
5. 安装步骤
6. 配置说明
7. 启动与验证
8. 监控与维护
9. 故障排查
10. 注意事项与禁忌

---

为什么选择 ECS + Docker Compose

✅ 核心原因

1. 数据合规与隐私（医疗行业红线）

❌ Dify 云服务 (SaaS)：数据上传到第三方服务器
✅ ECS 自建：数据 100% 在自己的阿里云账号内

影响：

• 三甲医院对科研数据出院有极严格管控
• 您可以对客户说："数据就在我们的私有云服务器上，未来可部署在医院内网"
• 符合 PRD 中的核心要求："数据 100% 本地"

2. 商业模式适配（私有化部署能力）

您的商业模式（PRD）:
  ├─ SaaS 版（多租户）
  ├─ 私有化部署（医院内网）
  └─ 单机版（Windows/Mac）

关键：

• Dify 云服务无法私有化交付（医院内网无法连接公有云）
• ECS + Docker Compose 可以直接打包成安装包，卖给医院做私有化部署
• 您现在的架构选型，是在为未来的商业模式铺路

3. 技术迁移成本（避开"以后再切回来"的陷阱）

RAG 系统迁移的复杂度：
  1. 文档被切片 (Chunking)
  2. 切片被向量化 (Embedding)
  3. 存入向量数据库 (Weaviate/Qdrant)
  4. Dify 云服务的向量数据很难无损导出

后果：3 个月后想切回自建，可能面临所有知识库需要重新上传、重新解析、重新嵌入

4. 网络性能与成本

路径对比	Dify 云服务	ECS 自建
网络路径	SAE → 公网 → Dify → 公网 → SAE	SAE → 阿里云内网(VPC) → ECS
延时	100-300ms	1-5ms
流量成本	消耗公网带宽	内网免费
大文件处理	慢且不稳定	毫秒级响应

影响场景：

• PKB 模块的批量文档上传
• ASL 模块的深度阅读 (Deep Read)
• 大量文档的向量化处理

---

部署架构图

┌─────────────────────────────────────────────────────────────┐
│                     阿里云 VPC (同一区域)                      │
│                                                               │
│  ┌─────────────┐         ┌─────────────────────────────┐   │
│  │  SAE (后端)  │ ←内网→  │      ECS (Dify 服务)         │   │
│  │             │         │                              │   │
│  │  Node.js    │         │  ┌─────────────────────┐    │   │
│  │  Backend    │         │  │  Docker Compose:     │    │   │
│  │             │         │  │  - Dify API          │    │   │
│  │             │         │  │  - Weaviate (向量DB)  │    │   │
│  │             │         │  │  - Nginx (反向代理)   │    │   │
│  │             │         │  └─────────────────────┘    │   │
│  └─────────────┘         └─────────────────────────────┘   │
│         │                                                    │
│         └──────────────→  RDS PostgreSQL 15                │
│                           (共享数据库)                       │
└─────────────────────────────────────────────────────────────┘

关键点：

• SAE 和 ECS 必须在同一个 VPC（内网通信）
• Dify 的 PostgreSQL 数据库可以和后端共用同一个 RDS 实例（不同 Schema）
• 向量数据库 Weaviate 运行在 ECS 的 Docker 中

---

前置准备清单

✅ 必需资源

资源类型	配置建议	预估费用	用途
ECS 服务器	2核4G / 系统盘40GB / 数据盘100GB	~200元/月	运行 Dify + Weaviate
RDS PostgreSQL	已有（共用）	0元（增量）	Dify 元数据存储
OSS 存储	已有（共用）	按量计费	文档存储
VPC 网络	已有（SAE所在VPC）	0元	内网通信

✅ 软件准备

# 本地开发机器需要安装（用于推送镜像）
- Docker Desktop
- 阿里云 CLI（可选）

# ECS 服务器需要安装（远程执行）
- Docker Engine
- Docker Compose

✅ 账号与权限

• 阿里云账号（已有）
• ECS 登录凭证（SSH密钥对）
• Docker 镜像仓库（阿里云容器镜像服务 ACR）

---

ECS 服务器配置

步骤 1：购买 ECS 实例

1. 登录阿里云控制台 → 云服务器 ECS → 创建实例

2. 基础配置：

   地域和可用区: 与 SAE 相同（如：华东1-杭州）
   实例规格: ecs.t6-c1m2.large (2核4G)
   镜像: Ubuntu 22.04 LTS 64位
   存储: 
     - 系统盘: ESSD云盘 40GB
     - 数据盘: ESSD云盘 100GB (挂载到 /data)
   

3. 网络配置：

   专有网络 VPC: 选择 SAE 所在的 VPC
   安全组: 创建新安全组，配置入方向规则（⚠️ 安全红线）：
     ✅ 允许 22/TCP    来源：您的办公室公网IP  # SSH管理
     ✅ 允许 80/TCP    来源：172.17.0.0/16      # Nginx（VPC内网访问）
     ❌ 拒绝 5000/TCP  来源：0.0.0.0/0          # Dify API禁止公网访问
     ❌ 拒绝 6379/TCP  来源：0.0.0.0/0          # Redis禁止公网访问
     ❌ 拒绝 8080/TCP  来源：0.0.0.0/0          # Weaviate禁止公网访问
     ✅ 拒绝 所有       来源：0.0.0.0/0          # 默认拒绝
   公网IP: 分配公网IPv4地址（用于SSH登录和镜像下载）
   
   ⚠️ 安全警告：
   - Dify API (5000)、Redis (6379)、Weaviate (8080) 绝对不能对公网开放
   - 只允许VPC内网访问（172.17.0.0/16）
   - 端口绑定到 127.0.0.1（见docker-compose.yaml配置）
   

4. 系统配置：

   登录凭证: 使用密钥对（推荐）或密码
   实例名称: dify-ecs-prod
   

步骤 2：连接到 ECS

# Windows 用户使用 PowerShell 或 Git Bash
ssh -i "your-key.pem" root@<ECS公网IP>

# 首次登录后，更新系统
apt update && apt upgrade -y

步骤 3：挂载数据盘

# 查看磁盘
lsblk

# 格式化数据盘（假设为 /dev/vdb）
mkfs.ext4 /dev/vdb

# 创建挂载点
mkdir -p /data

# 挂载
mount /dev/vdb /data

# 设置开机自动挂载
echo '/dev/vdb /data ext4 defaults 0 0' >> /etc/fstab

# 验证
df -h

步骤 4：配置 Swap 分区（关键！避免 OOM）

为什么必须配置 Swap？

• 您的 ECS 是 2核4G 内存
• Dify 全家桶（API+Worker+Web+Redis+Weaviate+Nginx）空载就需要 3GB+
• 有人上传大文件或进行向量检索时，极易发生 OOM（内存溢出）崩溃
• Swap 是内存的"救生圈"，关键时刻能保证服务不崩溃

# 创建 4GB Swap 分区
fallocate -l 4G /swapfile

# 设置权限（必须是 600，否则不安全）
chmod 600 /swapfile

# 格式化为 Swap
mkswap /swapfile

# 启用 Swap
swapon /swapfile

# 设置开机自动挂载
echo '/swapfile none swap sw 0 0' >> /etc/fstab

# 验证 Swap 已启用
free -h
# 应该看到 Swap 一行显示 4GB

# 优化 Swap 使用策略（可选）
# swappiness=10 表示尽量使用物理内存，只在必要时用 Swap
echo 'vm.swappiness=10' >> /etc/sysctl.conf
sysctl -p

步骤 5：安装 Docker

# 1. 卸载旧版本（如果有）
apt remove docker docker-engine docker.io containerd runc

# 2. 安装依赖
apt install -y ca-certificates curl gnupg lsb-release

# 3. 添加 Docker 官方 GPG key
mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 4. 设置 Docker 仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. 安装 Docker Engine
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 6. 启动 Docker
systemctl start docker
systemctl enable docker

# 7. 验证安装
docker --version
docker compose version

步骤 6：配置 Docker 镜像加速（可选但推荐）

# 阿里云镜像加速器（登录阿里云控制台获取专属地址）
mkdir -p /etc/docker
cat > /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": ["https://<your-id>.mirror.aliyuncs.com"]
}
EOF

systemctl daemon-reload
systemctl restart docker

---

安装步骤

步骤 1：准备 Dify 部署目录

# 在 ECS 上创建目录
mkdir -p /data/dify
cd /data/dify

# 克隆 Dify 官方仓库（使用稳定版本）
git clone https://github.com/langgenius/dify.git
cd dify

# 切换到稳定版本（建议使用最新的 release 版本）
git checkout tags/0.11.2  # 替换为最新稳定版本

# 进入 docker 目录
cd docker

# ⚠️ 重要：使用官方的 docker-compose.yaml
# 不要自己手写或大幅删减！官方配置包含了完整的服务（含 Nginx 网关）

步骤 2：配置环境变量

# 复制配置模板
cp .env.example .env

# 编辑配置文件
nano .env

关键配置项（必须修改）：

# ========= 核心配置 =========
# 安装模式：self-hosted（自建）
INSTALL_MODE=self-hosted

# 密钥（必须修改，使用强密码）
SECRET_KEY=<生成一个随机字符串，至少32位>
# 生成方法：openssl rand -base64 32

# ========= 数据库配置 =========
# 使用阿里云 RDS PostgreSQL
DB_TYPE=postgres
DB_HOST=<RDS内网地址，如：rm-xxxx.pg.rds.aliyuncs.com>
DB_PORT=5432
DB_NAME=dify_prod
DB_USERNAME=dify_user
DB_PASSWORD=<your-password>

# 注意：需要在 RDS 中创建单独的数据库和用户
# 执行：CREATE DATABASE dify_prod;
#       CREATE USER dify_user WITH PASSWORD 'your-password';
#       GRANT ALL PRIVILEGES ON DATABASE dify_prod TO dify_user;

# ========= Redis 配置 =========
# Dify 必须使用 Redis（不能用 Postgres-Only）
# ⚠️ 重要：在 Docker Compose 网络中，使用服务名而不是 localhost！
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=<strong-password>

# ========= 向量数据库配置 =========
# 使用 Weaviate（Docker Compose 自动启动）
VECTOR_STORE=weaviate
WEAVIATE_ENDPOINT=http://weaviate:8080
WEAVIATE_API_KEY=<生成一个随机字符串>

# ========= 存储配置 =========
# 使用阿里云 OSS（推荐）
STORAGE_TYPE=aliyun-oss
ALIYUN_OSS_BUCKET_NAME=<your-bucket-name>
ALIYUN_OSS_REGION=oss-cn-hangzhou
ALIYUN_OSS_ACCESS_KEY_ID=<your-access-key-id>
ALIYUN_OSS_ACCESS_KEY_SECRET=<your-access-key-secret>

# 或使用本地存储（不推荐）
# STORAGE_TYPE=local

# ========= LLM 配置 =========
# 默认 LLM 提供商（您可以在 Web UI 中添加多个）
DEFAULT_LLM_PROVIDER=openai-api-compatible

# DeepSeek API（示例）
DEEPSEEK_API_KEY=<your-deepseek-api-key>
DEEPSEEK_API_BASE=https://api.deepseek.com/v1

# ========= API 配置 =========
# API 服务地址（内网地址）
API_URL=http://<ECS内网IP>:5000

# Web 服务地址（如果需要访问 Dify Web UI）
WEB_API_URL=http://<ECS公网IP>
WEB_URL=http://<ECS公网IP>

# ========= 日志配置 =========
LOG_LEVEL=INFO
LOG_FILE=/data/logs/dify.log

# ========= 其他配置 =========
# 时区
TZ=Asia/Shanghai

# 是否开启 Debug
DEBUG=false

步骤 3：检查 Docker Compose 文件（建议使用官方配置）

# ⚠️ 强烈建议：不要手写 docker-compose.yaml！
# 直接使用官方文件，它包含了完整的架构（含 Nginx 网关）

# 查看官方配置
cat docker-compose.yaml

官方架构包含的服务：

services:
  # 1. nginx - 入口网关（必需！）
  #    作用：路由请求到 API 和 Web，解决 CORS 问题
  #    /v1/* → API 服务
  #    /* → Web 服务
  
  # 2. api - Dify API 服务
  # 3. worker - 后台任务处理
  # 4. web - Web 前端界面
  # 5. redis - 缓存和任务队列（必需）
  # 6. weaviate - 向量数据库
  # 7. sandbox - 代码解释器（可选，但建议保留）
  #    作用：如果在 Dify 中使用"代码解释器"功能
  
  # 如果你删除了 nginx，会遇到：
  # - 前端访问 API 时 CORS 跨域错误
  # - API 路由 404 错误
  
  # 如果你删除了 sandbox，会遇到：
  # - "代码解释器"功能报错

仅需修改的部分（如果有特殊需求）：

# ⚠️ 安全配置：端口绑定到本地（防止公网访问）
services:
  redis:
    ports:
      - "127.0.0.1:6379:6379"  # ⚠️ 只监听本地，禁止公网访问
  
  weaviate:
    ports:
      - "127.0.0.1:8080:8080"  # ⚠️ 只监听本地，禁止公网访问
  
  # 示例：如果需要外网访问 Web UI（通过Nginx）
  nginx:
    ports:
      - "80:80"      # HTTP（允许VPC内网访问）
      - "443:443"    # HTTPS（需要配置证书）

⚠️ 安全红线：

# ❌ 绝对禁止（会被攻击）
services:
  redis:
    ports:
      - "6379:6379"  # 全世界可访问，Redis无密码会被清空
  
  weaviate:
    ports:
      - "8080:8080"  # 向量数据可能被窃取
  
  api:
    ports:
      - "5000:5000"  # 黑客可绕过后端消耗LLM额度

# ✅ 正确做法：绑定到127.0.0.1
services:
  redis:
    ports:
      - "127.0.0.1:6379:6379"  # 只能本机访问

❌ 错误做法：

# 不要删减服务！尤其是 nginx
services:
  api: ...
  worker: ...
  # ❌ 缺少 nginx（会导致前端无法访问 API）

✅ 正确做法：

# 保持官方 docker-compose.yaml 不变
# 只修改 .env 环境变量
# 如果确实需要调整，只添加端口映射等无害配置

步骤 4：创建必需目录

mkdir -p /data/dify/storage
mkdir -p /data/dify/logs
mkdir -p /data/dify/redis
mkdir -p /data/dify/weaviate

# 设置权限
chmod -R 755 /data/dify

步骤 5：初始化数据库

# 在 RDS 中创建 Dify 数据库（使用 psql 或 DBeaver）
# 连接到 RDS
psql -h <RDS内网地址> -U postgres -d postgres

# 执行
CREATE DATABASE dify_prod;
CREATE USER dify_user WITH PASSWORD 'your-password';
GRANT ALL PRIVILEGES ON DATABASE dify_prod TO dify_user;
\q

---

启动与验证

步骤 1：启动 Dify 服务

cd /data/dify/docker

# 拉取镜像（首次运行）
docker compose pull

# 启动服务（后台运行）
docker compose up -d

# 查看日志
docker compose logs -f api

# 等待服务启动（约30秒）

步骤 2：验证服务状态

# 1. 检查容器状态
docker compose ps

# 应该看到以下容器都是 Up 状态：
# - dify-api
# - dify-worker
# - dify-web (如果启用)
# - redis
# - weaviate

# 2. 检查 API 健康状态
curl http://localhost:5000/health

# 期望返回: {"status": "healthy"}

# 3. 检查 Weaviate 状态
curl http://localhost:8080/v1/meta

# 期望返回: JSON 格式的元数据

步骤 3：测试内网连通性

# 在 SAE 后端服务中测试（或在本地通过 VPN 连接到 VPC）
curl http://<ECS内网IP>:5000/health

# 如果返回 {"status": "healthy"}，说明内网连通正常

步骤 4：初始化 Dify（首次部署）

1. 访问 Dify Web UI（如果启用）：

   http://<ECS公网IP>
   

2. 创建管理员账号：

   • 邮箱：admin@your-domain.com
   • 密码：

3. 配置 LLM 提供商：

   • 进入 "设置" → "模型提供商"
   • 添加 DeepSeek/Qwen 等 API Key

步骤 5：配置后端环境变量

在 SAE 后端服务的环境变量中添加：

# Dify API 配置
DIFY_API_BASE=http://<ECS内网IP>:5000
DIFY_API_KEY=<从 Dify Web UI 中获取>

# 获取 API Key 的方法：
# Dify Web UI → 设置 → API Keys → 创建新密钥

---

配置说明

🔧 存储配置详解

选项 1：阿里云 OSS（推荐）

优势：

• 无限扩展
• 高可用（99.9%）
• 与 SAE 内网通信，速度快

配置：

STORAGE_TYPE=aliyun-oss
ALIYUN_OSS_BUCKET_NAME=your-bucket-name
ALIYUN_OSS_REGION=oss-cn-hangzhou
ALIYUN_OSS_ACCESS_KEY_ID=<your-id>
ALIYUN_OSS_ACCESS_KEY_SECRET=<your-secret>

注意：

• OSS Bucket 必须和 ECS 在同一区域
• 建议使用内网 Endpoint（如：oss-cn-hangzhou-internal.aliyuncs.com）
• 设置合理的生命周期规则（如：30天后转冷存储）

选项 2：本地存储（不推荐）

缺点：

• 磁盘空间有限
• 无法横向扩展
• 数据备份麻烦

仅适用于：测试环境或小规模部署

🔧 数据库配置详解

Dify 数据库与后端数据库分离

RDS PostgreSQL 实例
├─ 数据库 1: clinical_research (后端主数据库)
│   ├─ Schema: platform_schema
│   ├─ Schema: asl_schema
│   ├─ Schema: dc_schema
│   └─ ...
└─ 数据库 2: dify_prod (Dify 数据库)
    ├─ Schema: public
    └─ ...

优势：

• 数据隔离（安全）
• 独立备份策略
• 避免资源竞争

连接池配置：

# Dify 的连接池较小（因为异步任务多）
DB_MAX_CONNECTIONS=20

🔧 Redis 配置说明

为什么 Dify 必须用 Redis？

• Dify 的任务队列依赖 Redis（Celery）
• 短期缓存（如：API 限流）
• 不能用 PostgreSQL 替代（与您的后端 Postgres-Only 架构不同）

关键配置（避免连接失败）：

# ⚠️ 致命错误警告：
# 在 .env 中，REDIS_HOST 必须设置为服务名 "redis"
# 不是 "localhost"！

# ❌ 错误写法（会导致 API 无法启动）
REDIS_HOST=localhost

# ✅ 正确写法（Docker Compose 网络中使用服务名）
REDIS_HOST=redis

# 原理：
# - 在 Docker Compose 中，容器之间通过服务名通信
# - localhost 指的是容器自己，不是 Redis 容器
# - redis 会被 Docker 网络解析为 Redis 容器的内网 IP

安全加固：

# 1. 设置强密码
REDIS_PASSWORD=<至少16位随机字符串>

# 2. 仅监听内网（docker-compose 中已配置）
# Redis 容器不暴露端口到主机，仅在 Docker 网络内可访问

# 3. 禁用危险命令（可选）
# 在 docker-compose.yaml 中修改 Redis 启动命令
command: >
  redis-server 
  --requirepass ${REDIS_PASSWORD}
  --rename-command CONFIG ""
  --rename-command FLUSHALL ""
  --rename-command FLUSHDB ""

---

监控与维护

📊 日志管理

1. 查看实时日志

cd /data/dify/docker

# 查看所有服务日志
docker compose logs -f

# 查看特定服务日志
docker compose logs -f api
docker compose logs -f worker

2. 日志文件位置

/data/dify/logs/
├─ api.log          # API 服务日志
├─ worker.log       # Worker 日志
└─ error.log        # 错误日志

3. 日志轮转配置

# 安装 logrotate（Ubuntu 默认已安装）
apt install logrotate

# 创建配置文件
cat > /etc/logrotate.d/dify <<EOF
/data/dify/logs/*.log {
    daily
    rotate 30
    compress
    delaycompress
    notifempty
    create 0644 root root
    sharedscripts
    postrotate
        docker compose -f /data/dify/docker/docker-compose.yaml restart api worker
    endscript
}
EOF

📊 性能监控

1. 资源使用情况

# 查看容器资源占用
docker stats

# 查看磁盘使用
df -h /data

# 查看内存使用
free -h

2. 数据库连接监控

# 连接到 RDS 查看 Dify 的连接数
psql -h <RDS内网地址> -U postgres -d dify_prod -c "
  SELECT count(*) 
  FROM pg_stat_activity 
  WHERE datname = 'dify_prod';
"

3. Redis 监控

# 连接到 Redis 容器
docker exec -it dify-redis redis-cli -a <REDIS_PASSWORD>

# 查看信息
INFO
INFO memory
INFO stats

🔄 定期维护任务

每周任务

# 1. 清理 Docker 日志
truncate -s 0 $(docker inspect --format='{{.LogPath}}' dify-api)
truncate -s 0 $(docker inspect --format='{{.LogPath}}' dify-worker)

# 2. 清理无用的 Docker 资源
docker system prune -a --volumes -f

每月任务

# 1. 数据库 VACUUM（在低峰期执行）
psql -h <RDS内网地址> -U dify_user -d dify_prod -c "VACUUM ANALYZE;"

# 2. 检查磁盘碎片
e2fsck -f /dev/vdb

# 3. 备份配置文件
tar -czf /backup/dify-config-$(date +%Y%m%d).tar.gz /data/dify/docker/.env

---

故障排查

🔥 常见问题

问题 1：API 容器无法启动 - Redis 连接失败（高频错误）

症状：

docker compose ps
# 显示 dify-api 状态为 Exit 1 或不断重启

docker compose logs api
# 显示错误：
# redis.exceptions.ConnectionError: Error connecting to localhost:6379
# 或
# Cannot connect to Redis at localhost:6379

根本原因：

# ❌ .env 文件中配置错误
REDIS_HOST=localhost  # 这是错的！

解决方法：

# 1. 编辑 .env 文件
nano /data/dify/docker/.env

# 2. 修改 REDIS_HOST
REDIS_HOST=redis  # ✅ 改为服务名

# 3. 重启服务
docker compose down
docker compose up -d

# 4. 验证
docker compose logs api | grep -i redis
# 应该看到：Successfully connected to Redis

问题 2：前端访问 API 报 CORS 错误

症状：

浏览器控制台报错：
Access to XMLHttpRequest at 'http://xxx/v1/xxx' from origin 'http://yyy' 
has been blocked by CORS policy

根本原因：

• 缺少 Nginx 网关服务
• 或者 Nginx 配置错误

解决方法：

# 1. 确认 Nginx 容器是否运行
docker compose ps | grep nginx

# 2. 如果没有 Nginx，说明你删除了官方配置
# 解决方案：重新克隆官方仓库，使用完整的 docker-compose.yaml

cd /data/dify
rm -rf dify
git clone https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
# 重新配置 .env（参考前文）
docker compose up -d

问题 3：容器无法启动 - 数据库连接失败

症状：

docker compose logs api
# 显示错误：
# could not connect to server: Connection refused

排查步骤：

# 1. 检查 RDS 白名单
# 阿里云控制台 → RDS → 数据安全性 → 白名单设置
# 确认添加了 ECS 的内网 IP

# 2. 检查 .env 配置
DB_HOST=<RDS内网地址>  # 不是公网地址！
DB_PORT=5432
DB_NAME=dify_prod
DB_USERNAME=dify_user
DB_PASSWORD=<正确的密码>

# 3. 测试连接（在 ECS 上）
telnet <RDS内网地址> 5432
# 如果连接失败，检查安全组和白名单

问题 4：服务运行一段时间后崩溃（OOM 内存溢出）

症状：

dmesg | grep -i kill
# 显示：Out of memory: Killed process xxx (dify-api)

docker compose ps
# 容器不断重启

根本原因：

• 2核4G 内存不足
• 没有配置 Swap 分区

解决方法：

# 1. 立即配置 Swap（如果之前没配置）
fallocate -l 4G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab

# 2. 验证 Swap 已启用
free -h

# 3. 重启服务
docker compose restart

# 4. 长期方案：升级 ECS 到 4核8G

问题 2：API 返回 500 错误

排查步骤：

# 1. 查看 API 日志
docker compose logs -f api | grep ERROR

# 2. 检查数据库连接
docker exec -it dify-api sh
# 在容器内执行
python -c "
import psycopg2
conn = psycopg2.connect(
    host='<RDS地址>',
    database='dify_prod',
    user='dify_user',
    password='<password>'
)
print('Connection OK')
"

问题 3：向量搜索失败

排查步骤：

# 1. 检查 Weaviate 状态
curl http://localhost:8080/v1/meta

# 2. 查看 Weaviate 日志
docker compose logs weaviate

# 3. 重建索引（最后手段）
# 在 Dify Web UI 中：设置 → 数据集 → 重新索引

问题 4：内网连接失败（SAE 无法访问 ECS）

排查步骤：

# 1. 检查安全组规则
# 阿里云控制台 → ECS → 安全组 → 确认开放 5000 端口给 SAE 所在网段

# 2. 测试连通性（在 SAE 容器内执行）
telnet <ECS内网IP> 5000

# 3. 检查防火墙（在 ECS 上执行）
ufw status
# 如果启用了防火墙，添加规则：
ufw allow from <SAE网段> to any port 5000

🔄 重启服务

# 重启所有服务
cd /data/dify/docker
docker compose restart

# 重启单个服务
docker compose restart api

# 完全重建（如果修改了 docker-compose.yaml）
docker compose down
docker compose up -d

---

注意事项与禁忌

✅ 最佳实践

1. 定期备份

   # 每天自动备份（添加到 crontab）
   0 2 * * * pg_dump -h <RDS地址> -U dify_user dify_prod | gzip > /backup/dify_$(date +\%Y\%m\%d).sql.gz
   

2. 监控磁盘空间

   # 设置告警（当 /data 使用率 > 80% 时通知）
   # 可使用阿里云云监控服务
   

3. 使用内网域名

   # 为 ECS 设置内网域名（便于维护）
   # 在 SAE 中配置 DIFY_API_BASE=http://dify.internal:5000
   # 而不是写死 IP
   

4. 版本锁定

   # docker-compose.yaml 中使用具体版本号，不要用 latest
   image: langgenius/dify-api:0.11.2  # ✅ 推荐
   # image: langgenius/dify-api:latest  # ❌ 禁止（可能导致不兼容）
   

❌ 绝对禁止

1. 禁止在 .env 中使用 REDIS_HOST=localhost

   # ❌ 致命错误（会导致服务启动失败）
   REDIS_HOST=localhost
   
   # ✅ 正确配置（在 Docker Compose 中使用服务名）
   REDIS_HOST=redis
   

2. 禁止删减官方 docker-compose.yaml 的核心服务

   # ❌ 危险操作（会导致功能异常）
   # - 删除 nginx → 前端 CORS 错误
   # - 删除 worker → 异步任务失败
   # - 删除 sandbox → 代码解释器功能失效
   
   # ✅ 正确做法
   # 使用官方完整配置，仅修改 .env 环境变量
   

3. 禁止在 2核4G 的 ECS 上不配置 Swap

   # ❌ 危险（极易 OOM 崩溃）
   # 没有 Swap，内存用尽后服务直接被 Kill
   
   # ✅ 必须配置 Swap
   fallocate -l 4G /swapfile
   chmod 600 /swapfile
   mkswap /swapfile
   swapon /swapfile
   

4. 禁止在生产环境使用 DEBUG=true

   # 会暴露敏感信息（如：API Key、数据库密码）
   DEBUG=false  # ✅
   

5. 禁止使用弱密码

   # 必须使用强密码（至少16位，包含大小写、数字、特殊字符）
   SECRET_KEY=$(openssl rand -base64 32)
   REDIS_PASSWORD=$(openssl rand -base64 24)
   WEAVIATE_API_KEY=$(openssl rand -base64 24)
   

6. 禁止暴露 Redis 和 Weaviate 端口到公网

   # 官方配置默认不暴露这些端口，不要自己添加
   # ❌ 危险配置
   services:
     redis:
       ports:
         - "6379:6379"  # 会被攻击！
   
   # ✅ 正确做法：仅在 Docker 网络内访问
   

7. 禁止直接修改数据库

   # 不要手动修改 Dify 数据库的表结构或数据
   # 必须通过 Dify API 或 Web UI 操作
   

8. 禁止在 ECS 上运行其他无关服务

   # 这台 ECS 专门用于 Dify，不要部署其他应用
   # 避免资源竞争和安全风险
   

⚠️ 重要提醒

1. 数据主权

   • 所有向量数据和文档都存储在您的 ECS 和 OSS 上
   • 定期检查数据备份的完整性

2. 成本控制

   • ECS 按量付费 vs 包年包月（根据实际情况选择）
   • 监控 OSS 存储量和流量（避免超出预算）

3. 升级策略

   # 升级 Dify 版本前的步骤：
   # 1. 备份数据库
   # 2. 在测试环境验证
   # 3. 选择业务低峰期升级
   # 4. 做好回滚准备
   

4. 私有化部署路径

   当前架构 → 直接复制到客户环境
   ├─ 导出 docker-compose.yaml
   ├─ 导出 .env（敏感信息替换）
   ├─ 打包为安装脚本（一键部署）
   └─ 提供《私有化部署手册》
   

---

📚 附录

A. 生成强密码的方法

# 方法 1: 使用 openssl
openssl rand -base64 32

# 方法 2: 使用 pwgen
pwgen -s 32 1

# 方法 3: 使用 Python
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

B. Dify API 常用端点

# 健康检查
GET http://<ECS内网IP>:5000/health

# 创建数据集
POST http://<ECS内网IP>:5000/v1/datasets
Headers: Authorization: Bearer <API_KEY>
Body: {"name": "test-dataset"}

# 上传文档
POST http://<ECS内网IP>:5000/v1/datasets/{dataset_id}/documents
Headers: Authorization: Bearer <API_KEY>
Body: (multipart/form-data)

# 语义检索
POST http://<ECS内网IP>:5000/v1/datasets/{dataset_id}/retrieve
Headers: Authorization: Bearer <API_KEY>
Body: {"query": "xxx", "top_k": 5}

C. 相关文档链接

• Dify 官方文档
• Docker Compose 文档
• Weaviate 文档
• 阿里云 ECS 文档
• 阿里云 OSS 文档

---

文档维护：

• 如有问题或建议，请联系技术负责人
• 最后更新：2025-12-13
• 下次审查：2025-03-13