# 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](#为什么选择-ecs--docker-compose)
2. [部署架构图](#部署架构�?
3. [前置准备清单](#前置准备清单)
4. [ECS 服务器配置](#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 云服务的向量数据很难无损导出
```

**后果**�? 个月后想切回自建，可能面临所有知识库需要重新上传、重新解析、重新嵌�?
#### 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�?G / 系统�?0GB / 数据�?00GB | ~200�?�?| 运行 Dify + Weaviate |
| **RDS PostgreSQL** | 已有（共用） | 0元（增量�?| Dify 元数据存�?|
| **OSS 存储** | 已有（共用） | 按量计费 | 文档存储 |
| **VPC 网络** | 已有（SAE所在VPC�?| 0�?| 内网通信 |

### �?软件准备

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

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

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

## ECS 服务器配�?
### 步骤 1：购�?ECS 实例

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

2. **基础配置**�?   ```
   地域和可用区: �?SAE 相同（如：华�?-杭州�?   实例规格: ecs.t6-c1m2.large (2�?G)
   镜像: Ubuntu 22.04 LTS 64�?   存储: 
     - 系统�? ESSD云盘 40GB
     - 数据�? ESSD云盘 100GB (挂载�?/data)
   ```

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

4. **系统配置**�?   ```
   登录凭证: 使用密钥对（推荐）或密码
   实例名称: dify-ecs-prod
   ```

### 步骤 2：连接到 ECS

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

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

### 步骤 3：挂载数据盘

```bash
# 查看磁盘
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�?G 内存
- Dify 全家桶（API+Worker+Web+Redis+Weaviate+Nginx）空载就需�?3GB+
- 有人上传大文件或进行向量检索时，极易发�?OOM（内存溢出）崩溃
- Swap 是内存的"救生�?，关键时刻能保证服务不崩�?
```bash
# 创建 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

```bash
# 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 镜像加速（可选但推荐�?
```bash
# 阿里云镜像加速器（登录阿里云控制台获取专属地址�?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 部署目录

```bash
# �?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：配置环境变�?
```bash
# 复制配置模板
cp .env.example .env

# 编辑配置文件
nano .env
```

**关键配置�?*（必须修改）�?
```bash
# ========= 核心配置 =========
# 安装模式：self-hosted（自建）
INSTALL_MODE=self-hosted

# 密钥（必须修改，使用强密码）
SECRET_KEY=<生成一个随机字符串，至�?2�?
# 生成方法：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 文件（建议使用官方配置）

```bash
# ⚠️ 强烈建议：不要手�?docker-compose.yaml�?# 直接使用官方文件，它包含了完整的架构（含 Nginx 网关�?
# 查看官方配置
cat docker-compose.yaml
```

**官方架构包含的服�?*�?
```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，会遇到�?  # - "代码解释�?功能报错
```

**仅需修改的部�?*（如果有特殊需求）�?
```yaml
# ⚠️ 安全配置：端口绑定到本地（防止公网访问）
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（需要配置证书）
```

**⚠️ 安全红线�?*
```yaml
# �?绝对禁止（会被攻击）
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"  # 只能本机访问
```

**�?错误做法**�?```yaml
# 不要删减服务！尤其是 nginx
services:
  api: ...
  worker: ...
  # �?缺少 nginx（会导致前端无法访问 API�?```

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

### 步骤 4：创建必需目录

```bash
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：初始化数据�?
```bash
# �?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 服务

```bash
cd /data/dify/docker

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

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

# 查看日志
docker compose logs -f api

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

### 步骤 2：验证服务状�?
```bash
# 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：测试内网连通�?
```bash
# �?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
   - 密码�?strong-password>

3. **配置 LLM 提供�?*�?   - 进入 "设置" �?"模型提供�?
   - 添加 DeepSeek/Qwen �?API Key

### 步骤 5：配置后端环境变�?
�?SAE 后端服务的环境变量中添加�?
```bash
# 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 内网通信，速度�?
**配置**�?```bash
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
    └─ ...
```

**优势**�?- 数据隔离（安全）
- 独立备份策略
- 避免资源竞争

**连接池配�?*�?```bash
# Dify 的连接池较小（因为异步任务多�?DB_MAX_CONNECTIONS=20
```

### 🔧 Redis 配置说明

**为什�?Dify 必须�?Redis�?*
- Dify 的任务队列依�?Redis（Celery�?- 短期缓存（如：API 限流�?- 不能�?PostgreSQL 替代（与您的后端 Postgres-Only 架构不同�?
**关键配置（避免连接失败）**�?```bash
# ⚠️ 致命错误警告�?# �?.env 中，REDIS_HOST 必须设置为服务名 "redis"
# 不是 "localhost"�?
# �?错误写法（会导致 API 无法启动�?REDIS_HOST=localhost

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

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

**安全加固**�?```bash
# 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. 查看实时日志

```bash
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. 日志轮转配置

```bash
# 安装 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. 资源使用情况

```bash
# 查看容器资源占用
docker stats

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

# 查看内存使用
free -h
```

#### 2. 数据库连接监�?
```bash
# 连接�?RDS 查看 Dify 的连接数
psql -h <RDS内网地址> -U postgres -d dify_prod -c "
  SELECT count(*) 
  FROM pg_stat_activity 
  WHERE datname = 'dify_prod';
"
```

#### 3. Redis 监控

```bash
# 连接�?Redis 容器
docker exec -it dify-redis redis-cli -a <REDIS_PASSWORD>

# 查看信息
INFO
INFO memory
INFO stats
```

### 🔄 定期维护任务

#### 每周任务

```bash
# 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
```

#### 每月任务

```bash
# 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 连接失败（高频错误）

**症状**�?```bash
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
```

**根本原因**�?```bash
# �?.env 文件中配置错�?REDIS_HOST=localhost  # 这是错的�?```

**解决方法**�?```bash
# 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 配置错误

**解决方法**�?```bash
# 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：容器无法启�?- 数据库连接失�?
**症状**�?```bash
docker compose logs api
# 显示错误�?# could not connect to server: Connection refused
```

**排查步骤**�?```bash
# 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 内存溢出�?
**症状**�?```bash
dmesg | grep -i kill
# 显示：Out of memory: Killed process xxx (dify-api)

docker compose ps
# 容器不断重启
```

**根本原因**�?- 2�?G 内存不足
- 没有配置 Swap 分区

**解决方法**�?```bash
# 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�?G
```

#### 问题 2：API 返回 500 错误

**排查步骤**�?```bash
# 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：向量搜索失�?
**排查步骤**�?```bash
# 1. 检�?Weaviate 状�?curl http://localhost:8080/v1/meta

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

# 3. 重建索引（最后手段）
# �?Dify Web UI 中：设置 �?数据�?�?重新索引
```

#### 问题 4：内网连接失败（SAE 无法访问 ECS�?
**排查步骤**�?```bash
# 1. 检查安全组规则
# 阿里云控制台 �?ECS �?安全�?�?确认开�?5000 端口�?SAE 所在网�?
# 2. 测试连通性（�?SAE 容器内执行）
telnet <ECS内网IP> 5000

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

### 🔄 重启服务

```bash
# 重启所有服�?cd /data/dify/docker
docker compose restart

# 重启单个服务
docker compose restart api

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

---

## 注意事项与禁�?
### �?最佳实�?
1. **定期备份**
   ```bash
   # 每天自动备份（添加到 crontab�?   0 2 * * * pg_dump -h <RDS地址> -U dify_user dify_prod | gzip > /backup/dify_$(date +\%Y\%m\%d).sql.gz
   ```

2. **监控磁盘空间**
   ```bash
   # 设置告警（当 /data 使用�?> 80% 时通知�?   # 可使用阿里云云监控服�?   ```

3. **使用内网域名**
   ```bash
   # �?ECS 设置内网域名（便于维护）
   # �?SAE 中配�?DIFY_API_BASE=http://dify.internal:5000
   # 而不是写�?IP
   ```

4. **版本锁定**
   ```bash
   # docker-compose.yaml 中使用具体版本号，不要用 latest
   image: langgenius/dify-api:0.11.2  # �?推荐
   # image: langgenius/dify-api:latest  # �?禁止（可能导致不兼容�?   ```

### �?绝对禁止

1. **禁止�?.env 中使�?REDIS_HOST=localhost**
   ```bash
   # �?致命错误（会导致服务启动失败�?   REDIS_HOST=localhost
   
   # �?正确配置（在 Docker Compose 中使用服务名�?   REDIS_HOST=redis
   ```

2. **禁止删减官方 docker-compose.yaml 的核心服�?*
   ```bash
   # �?危险操作（会导致功能异常�?   # - 删除 nginx �?前端 CORS 错误
   # - 删除 worker �?异步任务失败
   # - 删除 sandbox �?代码解释器功能失�?   
   # �?正确做法
   # 使用官方完整配置，仅修改 .env 环境变量
   ```

3. **禁止�?2�?G �?ECS 上不配置 Swap**
   ```bash
   # �?危险（极�?OOM 崩溃�?   # 没有 Swap，内存用尽后服务直接�?Kill
   
   # �?必须配置 Swap
   fallocate -l 4G /swapfile
   chmod 600 /swapfile
   mkswap /swapfile
   swapon /swapfile
   ```

4. **禁止在生产环境使�?DEBUG=true**
   ```bash
   # 会暴露敏感信息（如：API Key、数据库密码�?   DEBUG=false  # �?   ```

5. **禁止使用弱密�?*
   ```bash
   # 必须使用强密码（至少16位，包含大小写、数字、特殊字符）
   SECRET_KEY=$(openssl rand -base64 32)
   REDIS_PASSWORD=$(openssl rand -base64 24)
   WEAVIATE_API_KEY=$(openssl rand -base64 24)
   ```

6. **禁止暴露 Redis �?Weaviate 端口到公�?*
   ```bash
   # 官方配置默认不暴露这些端口，不要自己添加
   # �?危险配置
   services:
     redis:
       ports:
         - "6379:6379"  # 会被攻击�?   
   # �?正确做法：仅�?Docker 网络内访�?   ```

7. **禁止直接修改数据�?*
   ```bash
   # 不要手动修改 Dify 数据库的表结构或数据
   # 必须通过 Dify API �?Web UI 操作
   ```

8. **禁止�?ECS 上运行其他无关服�?*
   ```bash
   # 这台 ECS 专门用于 Dify，不要部署其他应�?   # 避免资源竞争和安全风�?   ```

### ⚠️ 重要提醒

1. **数据主权**
   - 所有向量数据和文档都存储在您的 ECS �?OSS �?   - 定期检查数据备份的完整�?
2. **成本控制**
   - ECS 按量付费 vs 包年包月（根据实际情况选择�?   - 监控 OSS 存储量和流量（避免超出预算）

3. **升级策略**
   ```bash
   # 升级 Dify 版本前的步骤�?   # 1. 备份数据�?   # 2. 在测试环境验�?   # 3. 选择业务低峰期升�?   # 4. 做好回滚准备
   ```

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

---

## 📚 附录

### A. 生成强密码的方法

```bash
# 方法 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 常用端点

```bash
# 健康检�?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 官方文档](https://docs.dify.ai/)
- [Docker Compose 文档](https://docs.docker.com/compose/)
- [Weaviate 文档](https://weaviate.io/developers/weaviate)
- [阿里�?ECS 文档](https://help.aliyun.com/product/25365.html)
- [阿里�?OSS 文档](https://help.aliyun.com/product/31815.html)

---

**文档维护**�?- 如有问题或建议，请联系技术负责人
- 最后更新：2025-12-13
- 下次审查�?025-03-13