优炫智能问答系统 · 安装运维简明手册
适用：znwd-compose-images-delivery 镜像部署包 · Linux x86_64
按顺序操作：解压并配置 → 启动系统 → 测试问答 → 需要时接入微信客服。
Dify 用来管理知识库和问答流程；AstrBot 用来连接微信客服。首次启动会自动导入两套业务流程，不需要从头搭建。
一、安装并启动
1. 准备好再开始
- 一台能联网的 Linux x86_64 服务器，已安装 Docker、Docker Compose 和 Buildx，并有足够的磁盘空间。
- 完整的镜像部署包，以及
licenses/uxdb.lic数据库授权。授权需要适用于安装系统的服务器；不适用时，请联系管理员更换。 - 后续做问答和知识入库时，需要有效的通义模型密钥。
包内已包含部分镜像。首次启动仍需联网获取 Dify、Docling；启用解析服务时还需下载模型。网络慢时请耐心等待。
不确定 Docker 是否已安装？
执行下面的命令，确认都能显示版本信息；如报命令不存在，请先联系运维安装。
docker version
docker compose version
docker buildx version
2. 解压安装包
以下以安装包放在 /opt 为例。如果服务器上已经有同名部署目录，先备份原环境，不要直接覆盖。
cd /opt
tar -xzf znwd-v1.0.tar.gz
cd znwd-compose-images-delivery
3. 创建并填写配置
首次安装，在部署目录复制配置模板并打开：
cp .env.example .env
chmod 600 .env
vim .env
已有 .env 的系统不要重复执行复制命令，直接打开原文件。vim 中按 i 开始编辑；修改完成后按 Esc，输入 :wq 并回车保存。
首次安装时，至少检查并填写以下项目：
| 项目 | 怎么填写 |
|---|---|
PUBLIC_URL | 例如 http://服务器IP:3000；修改访问端口时与 DIFY_PORT 保持一致 |
UXDB_PASSWORD | 自己设置数据库密码，不能为空 |
DIFY_ADMIN_EMAIL | Dify 管理员邮箱，默认 admin@example.com |
DIFY_ADMIN_PASSWORD | 自己设置 Dify 登录密码，至少 8 位，包含字母和数字 |
ASTRBOT_USERNAME | AstrBot 管理员账号，默认 admin |
ASTRBOT_PASSWORD | 自己设置；留空时首次生成随机密码 |
TONGYI_API_KEY | 填写通义模型密钥；暂时没有可以留空，问答和入库前再配置 |
COMPOSE_PROFILES | 默认留空，不启用本地 MinerU 和 OCR；需要时填 ocr、mineru 或 mineru,ocr |
默认不启用本地 MinerU 和 OCR。需要 OCR 时填写 ocr；需要 MinerU 时填写 mineru；两者都需要时填写 mineru,ocr。MinerU 需要可用的 NVIDIA GPU 和容器运行时，首次启动还会构建较大的镜像并下载模型；OCR 首次启动也需要下载模型。未启用的解析服务不能直接使用。密码或密钥含 $、# 或空格时，用英文单引号包住整个值。
当前知识库流水线和售前问答中的文件解析节点会用到 MinerU；图片文字回填会用到 OCR。默认关闭时，这些节点对应的文件入库、附件解析或图片文字回填可能无法完成；需要相关功能时，请启用相应服务并检查 Dify 中的工具配置。
如果没有提前创建 .env，首次启动也会自动生成配置和随机密码；本手册以下按手动填写的配置说明。文件中如有同名项目，以后面一条为准。
4. 检查配置并启动
docker compose config -q
没有输出且没有报错是正常的，表示入口配置检查通过。接着启动：
docker compose up -d
启动命令会自动准备初始化工具、加载随包镜像、拉取所需镜像并启动服务。以后日常启动也用这一条。
5. 确认服务启动
在部署目录执行：
docker compose ps -a
docker compose -f compose.stack.yaml ps -a
入口的 install 显示 Exited (0)、ready 显示 Up 属于正常；业务服务中，初始化任务显示 Exited (0)、长期运行的服务显示 Up，带健康检查的显示 healthy。
自动生成和手动复制的配置都默认关闭 MinerU 和 OCR；需要时修改
.env中的COMPOSE_PROFILES，再执行docker compose up -d。
二、登录 Dify，配置问答
1. 找到登录地址和密码
在部署目录打开配置文件：
vim .env
查找以下项目。文件中如果同名项目出现多次，以后面一条为准；密码外层的英文单引号不需要输入。
| 项目 | 在 .env 中查看 |
|---|---|
| Dify 地址 | PUBLIC_URL，例如 http://服务器IP:3000 |
| Dify 邮箱和密码 | DIFY_ADMIN_EMAIL、DIFY_ADMIN_PASSWORD |
| AstrBot 账号和密码 | ASTRBOT_USERNAME、ASTRBOT_PASSWORD |
如果 AstrBot 密码留空，首次生成的账号和密码在 data/runtime/initial-access.json；如果后来在 AstrBot 中改过密码，以修改后的密码为准。
使用配置中的邮箱和密码登录 Dify。默认邮箱为 admin@example.com，密码使用第一部分设置的值；如采用自动生成配置，以 .env 中的值为准。
2. 配置模型密钥
如果首次启动前还没有配置模型密钥，在 .env 中填写管理员提供的值：
TONGYI_API_KEY=你的通义模型密钥
密钥含 $、# 或空格时，用英文单引号包住整个值。
保存后，在部署目录重新执行：
docker compose up -d
系统会尝试配置模型并发布流程。如果页面仍提示模型未配置或流程为草稿，请到 Dify 的模型供应商设置中检查凭据，并发布对应流程。更换已经配置过的模型密钥时，在 Dify 的模型供应商设置中更新。
3. 放入资料并测试
安装完成后，在 Dify 中检查这两套应用和对应知识库：
| 用途 | 应用 | 知识库 |
|---|---|---|
| 售前问答 | 售前知识库RAG | USQAS-售前知识库2.0 |
| 微信客服 | UXDB智能客服2.0 | USQAS-微信智能客服知识库2.0 |
进入知识库，上传一份内容清楚的测试资料，等待解析和索引完成；再打开对应应用，提一个资料中有答案的问题，检查回答及引用是否正确。两套应用分别测试一次。
后续修改了应用流程或知识库流水线，要在 Dify 中重新发布。模型、解析服务或工具提示异常时，先检查对应凭据和服务状态。
三、接入微信客服（需要时操作）
先确认 Dify 中的 UXDB智能客服2.0 已能正常回答。微信客服需要企业微信后台配置和外部可访问的 HTTPS 地址。
1. 填写企业微信配置
从微信客服后台取得企业 ID、具有客服接口权限的 Secret、回调 Token 和 EncodingAESKey，填写到 .env：
WECHAT_ENABLED=true
WECOM_CORPID=企业ID
WECOM_SECRET=客服接口Secret
WECOM_TOKEN=回调Token
WECOM_ENCODING_AES_KEY=回调EncodingAESKey
将等号右边替换为真实值；Token 和 EncodingAESKey 要与微信后台一致。值含 $、# 或空格时，用英文单引号包住整个值。保存后执行：
docker compose up -d
2. 检查 AstrBot 和回调地址
打开 http://服务器IP:6185，用第二部分找到的 AstrBot 账号登录。检查：
- Dify 对话已启用，提供商为
dify_app_default；程序会自动绑定客服应用的 API Key。 wecom平台已启用，“微信客服账号名”与微信后台的客服名称一致。模板默认名称是“优炫数据库技术客服”，不同就修改并保存。
请网络管理员准备微信平台可访问的 HTTPS 地址，并转发到服务器的默认回调端口：
微信后台填写：https://客服域名/callback/command
服务器接收： http://服务器IP:6195/callback/command
在微信后台保存地址、Token 和 EncodingAESKey，完成校验；如后台要求可信 IP 或接口授权，也要按提示配置。最后通过客服链接或二维码发一条测试消息，确认能收到正确回答。默认回调端口修改过时，使用实际的 WECOM_PORT。
四、日常维护和常见问题
命令都在部署目录执行。
| 想做什么 | 命令 |
|---|---|
再次启动或应用 .env 修改 | docker compose up -d |
| 看业务服务状态 | docker compose -f compose.stack.yaml ps -a |
| 看安装步骤的错误 | docker compose logs --tail=100 install |
| 看数据库、问答和微信日志 | docker compose -f compose.stack.yaml logs --tail=100 uxdb api worker astrbot |
| 看磁盘空间 | df -h |
启动时如果出现下载中断、unexpected EOF，可以先重试 docker compose up -d；仍失败时检查网络、代理和安装包校验值。如果出现 Exited (1) 或 unhealthy，查看对应日志；数据库授权、模型下载和微信回调问题需要分别按日志排查。
执行 docker compose config -q 后没有任何输出，通常表示入口配置检查通过；业务是否启动成功还要看上面的服务状态。
需要停机时，先停止业务项目，再停止入口项目：
docker compose -f compose.stack.yaml down
docker compose down
不要给以上命令加 -v，也不要删除 data/runtime。 备份时请运维人员同时保存 .env、licenses/、data/、外置模型目录和业务 Docker 数据卷；数据库需要一致性备份，只复制 data 文件夹并不完整。
遇到问题时，记录做到哪一步和对应报错。分享日志或截图前，去掉密码、模型密钥和微信密钥。