前置条件
| 项目 | 要求 |
|---|---|
| XDelivery Config | 拥有 Add Publication 权限的账号 |
| Reader | 可正常登录的 Reader 账号 |
| DITA-OT | 建议使用与服务器同版本的 DITA-OT 3.7.4 |
| 源文件 | DITA map、topics、images 及 common 依赖文件齐全 |
| 输出格式 | 必须使用 XHTML,严禁使用 HTML5 |
生成 XHTML 输出
oxygen 编辑器,执行 XHTML 为发布对象的操作:
输出必检项
-
输出根目录必须存在以下核心文件与目录:
输出根目录结构
index.html topicsimagescommonltr.css
-
index.html与所有 topic HTML 必须是 XML well-formed XHTML,文件头部包含标准 XML 声明与 XHTML 命名空间:XHTML 头部校验<?xml version="1.0" encoding="UTF-8"?> <html xmlns="http://www.w3.org/1999/xhtml">
- 若 map 引用了
../../common/...,确认目标文件真实存在;缺失时需先补齐或移除相关引用。
整理输出目录
1. 扁平化目录层级
部分 DITA-OT 工程会输出嵌套子目录(例如 FPGA\项目名 opics\... 与 FPGA\项目名\images\...)。需将 topics 与 images 移动至与 index.html 同级,并同步修正 HTML 中的相对路径。
index.html topicsimagescommoncommonltr.css
2. 清理非法文件名
DHS 解析器禁止文件名中包含以下特殊字符:
+ % @ # & ~ / \ : * ? " < > | ' , =
- 不得包含
_xi后跟数字的片段; - 不建议包含空格、圆括号
(); - 清除所有
.bak、.tmp、.list、.pp等临时或无效扩展名文件。
image84(1).png -> image84_1.png high_purity_...,_...html -> high_purity_..._...html
3. 校验链接闭包
- 包内所有文件均可通过
index.html的相对链接逐级到达(无孤立文件); - 全文无
http://127.0.0.1:5200/...等本地调试地址; - 无死链或指向包外的相对路径越界。
打包 Direct Helpset ZIP
进入输出目录内部,全选根目录下的内容文件与子文件夹直接压缩,切勿在上一级目录右键压缩整个文件夹。
FSUG-Man.zip ├── index.html ├── topics├── images├── common└── commonltr.css
FSUG-Man.zip
└── FSUG-Man ├── index.html
├── topics └── images\
在 XDelivery Config 中发布
1. 登录管理后台
https://<你的域名>/kbconfig
2. 新建 Direct Helpset
依次进入 Publications → 选择目标 Category(或 ROOT)→ 点击 Add Publication → 选择 Direct Helpset(勿选 File)。
| 字段 | 示例 | 填写规则 |
|---|---|---|
| External ID | DH_UG285 |
仅限字母、数字、下划线、连字符;禁止空格与中文 |
| Default Name | UG285 Gowin BSRAM-SSRAM |
手册显示名称,保存后在列表中选中该 Publication |
3. 添加语言并导入 ZIP
- 点击
Add Language,选择目标语言代码(如zh-CN或en-US)并保存。 - 在语言列表中选中该语言行,点击
Import,上传第 04 步生成的 ZIP 压缩包并确认。 - 导入完成后,检查语言行状态是否显示为
Content Present = true。若仍为false,请排查 ZIP 根目录与 XHTML 格式后重新导入。
在 Reader 中验证
在浏览器中访问以下 URL 规则打开已发布手册:
https://<你的域名>/kb/<langCode>/<External ID> # 示例: https://raycontentech.com/kb/zh-CN/DH_UG285 https://raycontentech.com/kb/en-US/DH_FSUG_X
测试账号参考(正式交付前请务必修改默认密码):kbreader / Reader_999!
- 左侧 TOC 目录树层级完整且可展开;
- 点击任意 topic 节点,右侧正文正常渲染;
- 图片加载清晰,
commonltr.css样式生效; - 多语言版本切换指向正确。
常见错误与处理
| 错误现象 | 根本原因 | 处理方法 |
|---|---|---|
Invalid externalId |
包内文件名含括号、空格、逗号等非法字符 | 重命名文件并同步更新 HTML 引用 |
Invalid file name |
存在 .bak 或未注册扩展名文件 |
删除冗余文件或修改为合法扩展名 |
element type "link" must be terminated |
HTML 未闭合标签,不符合 XML well-formed | 使用 Oxygen 编辑器 --format=xhtml 重新构建 |
| 导入成功但 Reader 页面空白 | 误用了 HTML5 输出,导致 DHS 无法解析 TOC | 改用 XHTML 输出重新打包导入 |
| 仅显示部分 topic | 部分页面不在 index.html 链接闭包内 |
在 map/index 中补齐链接或清理孤立文件 |
| 来源或页面链接打不开 | 链接硬编码指向 127.0.0.1 |
批量替换为相对路径或正式公网域名 |
互联网访问 平台管理员操作
普通内容发布者无需操作本节。公网部署推荐使用标准 443 端口反向代理:
ProxyPass /kb https://localhost:8444/kb ProxyPassReverse /kb https://localhost:8444/kb ProxyPass /lwa https://localhost:8444/lwa ProxyPassReverse /lwa https://localhost:8444/lwa
- 域名 DNS 已解析至服务器公网 IP,防火墙已放行 443 端口;
- TLS 证书覆盖实际访问域名;
- 安全边界:严禁将
8444、5200内部端口直接暴露至公网。 - 公网连通性验证地址:
https://<域名>/kb/<lang>/<External ID>
AI 助手配置 可选 · 平台管理员操作
AI 助手属于服务器端增强配置,普通发布者无法在 XDelivery Config 界面中直接开启。
- 将 Reader 的 XHTML 输出目录作为 RAG 知识语料库;
- 生成
ograg_manifest.xml清单文件; - 配置 RAG 路径参数:
TOP_DIR=<语料根>与DB_PATH=<metadata.db>; -
依次执行索引构建命令:
OG-RAG 索引构建
OG-RAG-Pipeline.exe extract OG-RAG-Pipeline.exe reindex OG-RAG-Pipeline.exe hypergraph
- 确认
/chatbot/chat同源反向代理路由畅通; - 在 Reader 的
custom-footer.js中挂载 AI 助手前端组件; - 发起业务提问验证,确认引用来源链接可直接跳转至对应 XDelivery HTML topic(当前 POC 已验证
UG285/FSUG-Man可正常问答并返回来源)。
发布检查清单
每次交付前请逐项核对以下 12 项基准(点击可实时勾选记录进度):
要领总结:用 Oxygen 编辑器生成 XHTML → 整理成 index.html 在根目录的 ZIP → 在 XDelivery Config 选择 Direct Helpset + Add Language + Import → 用 /kb/<lang>/<External ID> 验证。
切记:HTML5 虽能导入成功但 TOC 必定为空,生产交付必须使用 XHTML。