dify-app/docs/deployment-guide.md

完整部署指南

西安云美电子科技有限公司 - 企业知识库 版本：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

# 更新系统
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 克隆项目

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

2.2 配置环境变量

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 启动服务

# 拉取镜像
docker compose pull

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

# 查看状态
docker compose ps

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

2.4 验证部署

# 检查 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（生产环境必做）

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

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

---

日常运维

备份

# 数据库备份（建议设置 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

更新

cd docker
docker compose pull
docker compose up -d

监控

# 查看服务状态
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