# 完整部署指南

> 西安云美电子科技有限公司 - 企业知识库
> 版本：v1.0 | 创建时间：2026-06-06

---

## 部署架构概览

```
                        ┌─────────────────────┐
                        │    用户 (浏览器)     │
                        └──────────┬──────────┘
                                   │
                        ┌──────────▼──────────┐
                        │  Nginx (反向代理)    │  :80 / :443
                        │  SSL 终止 / 负载均衡  │
                        └──────────┬──────────┘
                                   │
                   ┌───────────────┼───────────────┐
                   │               │               │
            ┌──────▼──────┐ ┌─────▼─────┐ ┌──────▼──────┐
            │ Dify Web    │ │ Dify API  │ │ SSRF Proxy  │
            │ (React SPA) │ │ (Flask)   │ │ (Squid)     │
            │ :3000       │ │ :5001     │ │ :3128       │
            └─────────────┘ └─────┬─────┘ └─────────────┘
                                 │
                    ┌────────────┼────────────┐
                    │            │            │
             ┌──────▼──────┐ ┌──▼────┐ ┌─────▼──────┐
             │ PostgreSQL  │ │ Redis │ │  Qdrant    │
             │ :5432      │ │ :6379 │ │  :6333     │
             └─────────────┘ └───────┘ └────────────┘
```

---

## 第一步：服务器准备

### 1.1 系统要求

- Ubuntu 22.04 LTS（推荐）
- 最低 4 核 CPU / 8 GB RAM / 50 GB SSD
- 推荐 8 核 CPU / 16 GB RAM / 100 GB SSD

### 1.2 安装 Docker

```bash
# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装 Docker
curl -fsSL https://get.docker.com | sh

# 安装 Docker Compose（如未自带）
sudo apt install docker-compose-plugin -y

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

# 将当前用户加入 docker 组
sudo usermod -aG docker $USER
# 重新登录生效
```

---

## 第二步：部署 Dify

### 2.1 克隆项目

```bash
git clone http://git.xayunmei.com/yunmei/dify-app.git
cd dify-app
git checkout feature/dev
```

### 2.2 配置环境变量

```bash
cd docker

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

# 生成 SECRET_KEY
SECRET_KEY=$(openssl rand -hex 32)
echo "生成的 SECRET_KEY: $SECRET_KEY"

# 编辑 .env，填入实际值
nano .env
```

**必须修改的配置项**：

| 变量 | 说明 | 操作 |
|------|------|------|
| `SECRET_KEY` | 安全密钥 | 使用上面生成的值 |
| `POSTGRES_PASSWORD` | 数据库密码 | 设置强密码 |
| `REDIS_PASSWORD` | Redis 密码 | 设置强密码 |
| `DEEPSEEK_API_KEY` | DeepSeek API Key | 从 DeepSeek 平台获取 |

### 2.3 启动服务

```bash
# 拉取镜像
docker compose pull

# 启动所有服务
docker compose up -d

# 查看状态
docker compose ps

# 等待所有服务健康（约 30-60 秒）
docker compose ps --format "table {{.Name}}\t{{.Status}}"
```

### 2.4 验证部署

```bash
# 检查 API 服务
curl http://localhost:5001/health

# 检查 Web 服务
curl -I http://localhost:80
```

---

## 第三步：初始化 Dify

### 3.1 创建管理员账号

1. 浏览器访问 `http://<服务器IP>:80`
2. 首次访问进入设置向导
3. 填写邮箱和密码，创建管理员账号
4. 设置管理员姓名

### 3.2 配置模型提供者

1. 进入 Dify 控制台
2. 导航到 **设置 → 模型提供者**
3. 添加 **DeepSeek**：
   - API Base: `https://api.deepseek.com`
   - API Key: 填入实际的 DeepSeek API Key
4. 验证连接成功

### 3.3 创建知识库

按 `docs/knowledge-base-structure.md` 中的结构创建知识库：

| 知识库名称 | 说明 |
|-----------|------|
| KB-COMP-公司概况 | 公司简介、组织架构 |
| KB-PROD-产品技术 | 产品手册、技术规范 |
| KB-QUAL-质量管理 | 质量体系、检测标准 |
| KB-RULE-制度流程 | 管理制度、审批流程 |
| KB-TRAIN-培训学习 | 培训材料 |
| KB-PROJ-项目档案 | 项目文档 |
| KB-FAQ-常见问题 | FAQ |

**每个知识库的分段配置**：
- 分段模式：自动
- 最大分段长度：500 tokens
- 重叠长度：50 tokens

### 3.4 上传文档

1. 准备各部门的知识库文档（PDF/Word/Markdown）
2. 按分类上传到对应知识库
3. 等待索引完成
4. 测试检索效果

---

## 第四步：配置对话应用

### 4.1 创建聊天应用

1. Dify 控制台 → **创建应用 → 聊天助手**
2. 应用名称：**云美知识助手**
3. 导入 DSL 配置（可选）：
   - 应用设置 → 右上角 → **导入 DSL**
   - 上传 `dsl/app-config.yaml`
4. 或手动配置（参考 `dsl/app-config.yaml` 中的参数）

### 4.2 配置提示词

复制 `prompts/system-prompt.md` 中的系统提示词到应用配置。

### 4.3 关联知识库

在应用的「知识库」设置中，关联已创建的所有知识库。

### 4.4 配置推荐问题

复制 `prompts/system-prompt.md` 中的推荐问题到应用配置。

### 4.5 测试应用

使用 Dify 内置的调试界面进行测试：

```
测试问题1：公司的组织架构是怎样的？
测试问题2：差旅报销的标准和流程是什么？
测试问题3：质量管理体系审核周期是多久？
```

对照 `tests/test-cases.md` 执行完整测试。

---

## 第五步：发布与接入

### 5.1 发布应用

1. 点击应用右上角 **发布**
2. 选择 **运行环境**（生产环境）
3. 确认发布

### 5.2 获取 API Key

1. 应用 → **访问 API**
2. 创建 API Key
3. 保存 Key（只显示一次）

### 5.3 接入企业微信（可选）

参考 `docs/api-integration.md` 中的企业微信集成示例。

### 5.4 配置 Nginx SSL（生产环境必做）

```bash
# 将 SSL 证书放入 nginx/ssl/ 目录
mkdir -p nginx/ssl

# 编辑 Nginx 配置，启用 HTTPS
# 修改 .env 中的 NGINX_SSL_PORT
```

---

## 日常运维

### 备份

```bash
# 数据库备份（建议设置 cron 每日执行）
docker compose exec db pg_dump -U postgres dify > /backup/dify_$(date +%Y%m%d).sql

# 向量库备份
docker compose exec qdrant curl -X POST http://localhost:6333/snapshots
```

### 更新

```bash
cd docker
docker compose pull
docker compose up -d
```

### 监控

```bash
# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f --tail=100 api
docker compose logs -f --tail=100 worker

# 查看资源占用
docker stats --no-stream
```

---

## 故障排查速查

| 现象 | 排查命令 | 常见原因 |
|------|---------|---------|
| 页面打不开 | `docker compose ps` | 服务未启动 |
| 模型不回复 | `docker compose logs api` | API Key 无效/过期 |
| 知识库不检索 | `docker compose logs worker` | Worker 异常/索引未完成 |
| 数据库连接失败 | `docker compose logs db` | 密码不一致 |
| 磁盘空间不足 | `df -h` | 日志/数据膨胀 |

---

_最后更新: 2026-06-06_