WeKnora/website-docs
linus-liu-web 8319d59dd0
feat(datasource/dingtalk): 摄取钉钉"上传文件"(docx/pptx/xlsx/pdf) (#3786)
* feat(datasource/dingtalk): 摄取钉钉"上传文件"(docx/pptx/xlsx/pdf)

钉钉连接器此前只导入原生 .adoc 文档:知识库里的上传文件既不会出现在选择器里,
也不会被同步,而且没有任何提示。

- 节点判定拆成 isOnlineDocument / isBinaryDocument / binaryContentType,isDocument()
  变成"在线文档 ∪ 二进制文档",上传文件因此可被枚举与摄取;表格(axls)等其它原生
  类型仍不在其中,避免枚举出同步读不了的节点。
- 上传文件通过钉盘下载 API 逐字节传输,交给 WeKnora 自己的解析器:先用
  /v2.0/doc/dentries/{id}/queryDentryId 把节点 UUID 换成数字 spaceId/dentryId
  (存储 API 拒绝非数字 spaceId),再取预签名 URL 下载。
- 大小上限加在传输上而不是列表元数据上:node.size 与存储对象并不一致。
- 预签名 URL 短命且带版本,传输失败会用新签名重试。
- Validate 对上传文件"解析位置但不传 payload",凭证校验不必为每个候选文件下载
  数 MB;adoc 仍走 blocks API。
- 同步按类型分派:adoc 渲染 blocks,上传文件落原始字节并带上具体 MIME 类型与只含
  一个扩展名的文件名;下载失败与读取失败一样是可重试的失败项,不推进游标。

本提交只含 C(上传文件摄取)。不含:校验循环容错(A)、跳过项日志与可见性(B)、
原生表格 axls(D)、多维表/手工引用/前端(E)。

* test(datasource/dingtalk): 上传文件用例改用合成文档名与占位 ID

- 夹具、断言与文件名注释里的文档名统一换成合成名 Employee-Handbook.docx,
  用例语义不变:仍覆盖"名字已带扩展名时不重复追加"与 PK\x03\x04 字节断言。
- 去掉测试注释里"as verified against the live tenant"的表述,改为描述调用顺序。
- dentry 响应示例与用例中的数字 ID 换成明确占位符,不再出现可被误认的真实 ID。

* fix(datasource/dingtalk): 上传文件摄取改为数据源级开关,超限不再重试

评审意见(#3786):上传文件是本次新增的摄取路径,存量数据源升级后无需用户显式启用
就会在下一次同步(含增量)开始下载并向量化所选范围内的 docx/pptx/xlsx/pdf,可能
增加存储与 embedding 成本;同时单次下载里超出体积上限被当成可重试错误,没有
Content-Length 的超大文件会重签名再下满 3 次。

- 新增 `Settings.include_uploaded_files`(默认 false,未设置/非法值一律按 false)。
  读取走与本仓库语雀连接器同名的 settingBool(v, def),并新增 documentSettings /
  parseDocumentSettings 承载开关。
- 判定拆成"有没有读取路径"(isDocument)与"这个数据源收不收"(isIngestible):
  Validate 的探测、ListResources、全量同步与增量同步(共用 scanWorkspace)四处
  全部改用 isIngestible,关闭时行为与 main 一致。
- skipReason 对"能读但没开开关"的上传文件给出可操作的原因:说明
  include_uploaded_files 未启用,而不是伪装成类型不支持;媒体文件与真正没有
  摄取路径的类型保持原有说法。
- readLimited 改为返回哨兵错误 errDocumentTooLarge(同时包装上限字节数),
  fetchSigned 据此返回 retryable=false:体积是对象的属性,新签名只会拿到同样的
  字节。普通读错误仍然 retryable=true,仍会重签名重试。
- 前端数据源编辑弹窗(同步策略步骤)加对应开关,未触碰时不写回 settings;5 个
  语言包补齐文案。
- website-docs 钉钉一节写明支持范围、默认值、64 MiB 单文件上限与成本影响。

测试补 include_uploaded_files 的未设置/显式关闭/显式开启三种状态:校验、资源列表、
全量同步、增量同步四处各自断言,直接选择上传文件在关闭时仍是失败的资源;流式超限
用例断言签名查询与对象下载各只发生一次,另加"普通读错误仍重试"的用例。

---------

Co-authored-by: linus-liu-web <11640009+linus-liu-web@users.noreply.github.com>
Co-authored-by: linus-liu-web <linus-liu-web@users.noreply.github.com>
2026-10-09 10:56:04 +08:00
..
.vitepress fix(website-docs): serve everything but the homepage from /docs/ 2026-09-24 15:24:16 +08:00
01-getting-started fix(docparser): 云解析超时改为跟随既有配置,不再硬编码 (#3891) 2026-10-08 14:02:42 +08:00
02-architecture feat: index and recall images with multimodal embedding models (#3683) 2026-10-08 18:19:53 +08:00
03-features feat(datasource/dingtalk): 摄取钉钉"上传文件"(docx/pptx/xlsx/pdf) (#3786) 2026-10-09 10:56:04 +08:00
04-api fix(wiki): resolve titles for unloaded backlinks (#3931) 2026-10-09 10:50:52 +08:00
05-clients chore: bump version to 0.8.2 2026-09-24 14:18:55 +08:00
06-development docs: count 29 built-in model vendors and list Hugging Face TEI and Pinecone (#4048) 2026-10-08 18:03:07 +08:00
07-releases docs: date the v0.8.2 release and describe it in the READMEs 2026-09-24 14:18:55 +08:00
deploy feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
homepage docs: count 29 built-in model vendors and list Hugging Face TEI and Pinecone (#4048) 2026-10-08 18:03:07 +08:00
public docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
sample-data feat(website-docs): add quickstart sample data and local MCP demo 2026-08-06 19:54:40 +08:00
scripts fix(docs): spawn nested npm through Node on Windows 2026-09-29 17:19:25 +08:00
shared fix(website-docs): serve everything but the homepage from /docs/ 2026-09-24 15:24:16 +08:00
.dockerignore feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
.gitignore feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
.nvmrc feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
Dockerfile docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
MIGRATION.md docs: 迁移有效文档至 website-docs 并清理旧文档 (#3580) 2026-09-22 23:25:40 +08:00
README.md fix(website-docs): serve everything but the homepage from /docs/ 2026-09-24 15:24:16 +08:00
VERSION chore: bump version to 0.8.2 2026-09-24 14:18:55 +08:00
docker-entrypoint.sh docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
index.md feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
package-lock.json chore: bump version to 0.8.2 2026-09-24 14:18:55 +08:00
package.json chore: bump version to 0.8.2 2026-09-24 14:18:55 +08:00

README.md

WeKnora 官网与文档

website-docs/ 包含官网、文档、共享样式和全部构建部署脚本,可独立复制和构建,不依赖仓库外层文件。官网和文档共用一个域名、一次构建和一份部署产物。

产品、部署、API 和开发文档统一在这里维护。旧 docs/ 的有效内容已按主题合并,过时和重复正文已删除;迁移取舍及仍保留的工程资源见迁移记录;该记录仅供维护者使用,不发布到站点。

  • /:产品首页。
  • /docs/:直接进入“快速上手”。
  • /docs/…:完整文档,保留分类导航、搜索和侧栏。

站点只占用这两个路径:根目录下只有 index.html、404.html 和 docs/。官网的脚本、样式和图片都放在 /docs/_home/ 下,所以上游网关只需转发 /(精确匹配)和 /docs/ 前缀。build 会拒绝引用这两个路径以外资源的页面。

顶栏高 64px、横向铺满。两边使用 README 原版商标,共用颜色、字体和深浅色偏好;Logo 在当前标签返回官网。官网和文档各自使用适合当前页面的导航。

发布方式:静态文件 + Nginx

1. 准备部署包

使用 Node.js 24,在仓库的 website-docs/ 目录执行。首次构建或依赖锁文件变更后,先安装依赖:

cd website-docs
npm run setup
npm run build
npm run package:site

build 会编译官网、检查文档链接和 Mermaid、编译文档,并校验合并后的资源路径。全部通过后更新 static-site/;package:site 将其打包到 releases/。

2. 上传并解压

只需把压缩包上传到服务器。服务器不需要 Node.js,也不需要 WeKnora 后端或独立文档服务。

每次发布使用一个新的空目录,避免混入旧站点文件。下面的 20260915-1 是示例发布编号,后续发布换一个编号:

sudo mkdir -p /srv/www/weknora/releases/20260915-1
sudo tar -xzf weknora-site-v0.8.2.tar.gz -C /srv/www/weknora/releases/20260915-1

解压后该目录下应直接有 index.html、404.html、docs/,无需再套一层 static-site/。

3. 配置域名根目录

以 deploy/nginx.conf 为模板添加站点配置,修改:

server_name 你的域名;
root /srv/www/weknora/releases/20260915-1;

如果域名已有 HTTPS 配置,保留原来的证书及监听设置,把模板中的 root、index 和 location 规则合入现有站点配置。域名应指向这台服务器。

必须保留文档的 .html 路由解析规则;不要把所有未知路径回退到官网 index.html。当前构建部署在域名根路径,不支持直接放进 /weknora/ 等子目录。

检查配置后重载:

sudo nginx -t
sudo nginx -s reload

4. 确认上线

访问以下路径:

  • /:官网。
  • /docs/:快速上手。
  • /docs/03-features/23-memory:长期记忆文档,直接打开和刷新均正常。
  • /docs/not-found:返回 404。

再确认搜索、深浅色切换和 Logo 返回官网正常。

后续更新重复构建、打包、上传到新目录,再修改 Nginx root 并重载。需要回滚时,将 root 改回上一发布目录。确认新版本稳定后再清理旧发布目录。

可选:Docker 部署

从干净源码即可构建,无需在宿主机安装 Node.js 或提前生成静态文件。Dockerfile 使用两个阶段:Node.js 24 按两份锁文件安装依赖并构建官网与文档,最终 Nginx 镜像只包含静态产物和服务配置。

在仓库根目录执行:

docker build -t weknora-site:0.8.2 website-docs
docker run -d --name weknora-site --restart unless-stopped -p 8080:80 weknora-site:0.8.2

访问 http://服务器地址:8080/。如使用域名和 HTTPS,让现有反向代理转发到该端口即可。镜像内已经包含官网、文档和 Nginx 路由配置。

容器内的 Nginx 默认监听 80 端口,可以用环境变量 WEBSITE_NGINX_PORT 修改,无需重新构建。使用 --network host,或者部署平台要求容器监听指定端口时,这样设置:

docker run -d --name weknora-site --restart unless-stopped -e WEBSITE_NGINX_PORT=8080 -p 8080:8080 weknora-site:0.8.2

只是想换一个对外端口时,改 -p 左侧的宿主机端口就够了,例如 -p 9000:80。

也可以只复制 website-docs/ 目录,在该目录执行 docker build -t weknora-site:0.8.2 .。构建上下文必须是 website-docs/,宿主机的依赖、旧构建产物和部署包由 .dockerignore 排除。

从旧文档镜像迁移时,将容器端口映射或反向代理目标端口从 8081 改为 80(宿主机端口可自行选择,例如 -p 8081:80)。域名根路径 / 现在提供官网,/docs/ 提供文档,反向代理需覆盖整个站点并保留请求路径。容器使用 Nginx 官方镜像的默认入口,无需额外的 docker-entrypoint.sh。

构建后可在安装了 Node.js 24 和 Docker 的机器上执行以下检查,无需安装 npm 依赖。检查会临时启动容器并自动清理,验证两站路由、静态资源、404、压缩和响应头:

cd website-docs
npm run test:docker -- weknora-site:0.8.2

本地开发

使用 Node.js 24 LTS(目录内提供 .nvmrc,使用 nvm 时可执行 nvm use)。首次获取源码后安装依赖(分别按文档和官网的锁文件安装):

cd website-docs
npm run setup
npm run build
npm run preview

预览地址:http://127.0.0.1:3000/。修改源码后重新构建并刷新;可用 npm run preview -- --port 8080 指定其他端口。

npm run check
npm run test:integration

集成检查需要安装 Google Chrome,验证主题同步、两边导航、搜索、手机端控件及直达文档路由。可用 SITE_TEST_URL 指定待验证的站点。

开发时可分别使用 npm run dev:homepage(官网)和 npm run dev:docs(文档)获得热更新;完整站内跳转请使用统一构建后的 npm run preview。

npm run build:docs 只编译文档,npm run build:homepage 只编译官网;正式发布使用 npm run build,输出会同时包含两者。VERSION 是这份站点构建使用的发布版本。

工程目录(相对于 website-docs)

  • homepage/:Next.js 官网源码、品牌素材及独立依赖锁文件。
  • 01-getting-started/ 至 06-development/:文档正文,原有路径不变。
  • .vitepress/:文档站配置与主题。
  • public/、sample-data/:文档截图和示例。
  • shared/:品牌变量、顶栏样式及共用图标。
  • scripts/:统一构建、检查、预览和打包。
  • static-site/:唯一的部署目录,由构建生成。
  • deploy/、Dockerfile:Nginx 和 Docker 部署配置。
  • releases/:生成的部署压缩包。

品牌素材来源见 homepage/BRAND-ASSETS.md。产品视频使用 README 中的 GitHub 原始附件,播放需要访问 GitHub;页面、文档和截图随包部署。