xwiki-sync v1.0 功能说明书

根据目前日志和目录结构，你的 xwiki-sync v1.0 稳定版 已经具备一个完整的“共享目录 → XWiki 文档库”的同步闭环： 

 

 

 文件新增 ✅ 

 

 

 文件修改 ✅ 

 

 

 文件删除同步 ✅ 

 

 

 XWiki 页面创建/更新/删除 ✅ 

 

 

 自动空间映射 ✅ 

 

 

 文件 Hash 增量检测 ✅ 

 

 

 SQLite 状态记录 ✅ 

 

 

 Docker 运行 ✅ 

 

 

 Tika 文档解析 ✅ 

 

 

 下面整理成正式归档文档，建议保存为： 

 /opt/xwiki/sync/docs/xwiki-sync-v1.0功能说明书.md

 

 

 xwiki-sync v1.0 功能说明书 

 1. 项目名称 

 xwiki-sync 

 版本： 

 v1.0 Stable

 

 发布日期： 

 2026-07-18

 

 用途： 

 

 将 SMB 共享目录中的文档自动同步到 XWiki，实现企业内部文档自动化管理。 

 

 

 2. 系统架构 

 整体架构： 

 SMB共享目录

 |

 |

 scanner/smb.py

 |

 |

 文件扫描模块

 core/scanner.py

 |

 |

 文件状态数据库

 SQLite Database

 |

 +-----------+-----------+

 | |

 新文件 已存在文件

 | |

 | Hash检测

 | |

 +-----------+-----------+

 |

 sync/processor.py

 |

 +-----------+-----------+

 |

 文档解析

 extractor/tika.py

 |

 |

 XWiki REST API

 |

 |

 XWiki页面

 

 

 3. 目录结构说明 

 sync

│

├── app.py

│

├── clients

│ └── xwiki.py

│

├── core

│ ├── database.py

│ ├── hash.py

│ ├── hashdb.py

│ └── scanner.py

│

├── extractor

│ └── tika.py

│

├── scanner

│ └── smb.py

│

├── sync

│ └── processor.py

│

├── models

│ └── fileinfo.py

│

├── config.yaml

│

├── Dockerfile

│

└── upgrade_db.py

 

 

 4. 核心功能说明 

 4.1 文件扫描功能 

 模块： 

 scanner/smb.py

core/scanner.py

 

 功能： 

 定时扫描共享目录。 

 默认周期： 

 60秒

 

 扫描结果： 

 例如： 

 /data/wiki_attach/test.txt

 

 转换为同步任务： 

 space = wiki_attach

page = test

 

 

 4.2 文件路径映射规则 

 根目录文件 

 例如： 

 /data/web.config

 

 转换： 

 XWiki:

Main.web

 

 说明： 

 默认进入 Main 空间

 

 

 一级目录 

 例如： 

 /data/wiki_attach/docker安装.txt

 

 转换： 

 Space:

wiki_attach

Page:

docker安装

 

 XWiki： 

 wiki_attach.docker安装

 

 

 多级目录 

 例如： 

 /data/a/b/c.txt

 

 转换： 

 Space:

a

Page:

b_c

 

 规则： 

 目录名称_Page名称

 

 

 4.3 文件类型支持 

 当前通过： 

 Apache Tika

 

 解析。 

 支持： 

 

 

 

 类型 

 状态 

 

 

 

 

 TXT 

 支持 

 

 

 DOCX 

 支持 

 

 

 DOC 

 支持 

 

 

 PDF 

 支持 

 

 

 XLSX 

 支持 

 

 

 PPTX 

 支持 

 

 

 

 

 4.4 增量同步 

 核心： 

 core/hash.py

core/database.py

 

 机制： 

 文件计算 SHA Hash。 

 例如： 

 第一次： 

 test.txt

hash:

abc123

 

 数据库保存： 

 文件路径

hash

space

page

 

 下一次扫描： 

 如果： 

 hash相同

 

 跳过： 

 日志： 

 跳过:

xxx 未变化

 

 避免重复写入 XWiki。 

 

 4.5 新文件同步 

 流程： 

 发现文件

↓

计算Hash

↓

数据库不存在

↓

Tika解析

↓

创建XWiki页面

↓

保存数据库

 

 日志： 

 例如： 

 新文件:

wiki_attach.docker镜像导出和导入

页面创建成功

同步完成

 

 

 4.6 文件修改同步 

 检测： 

 旧hash != 新hash

 

 流程： 

 重新解析

↓

更新XWiki页面

↓

更新数据库hash

 

 日志： 

 文件变化:

xxx

页面更新成功

 

 

 4.7 删除同步 

 这是 v1.0 新增稳定功能。 

 流程： 

 共享目录： 

 test.txt

删除

 

 扫描发现： 

 数据库存在

实际文件不存在

 

 执行： 

 XWiki REST DELETE

 

 日志： 

 发现删除文件:

/data/test.txt

删除XWiki页面:

Main.test

XWiki删除成功

删除完成

 

 

 5. XWiki REST接口 

 客户端： 

 clients/xwiki.py

 

 功能： 

 测试连接 

 接口： 

 GET

/rest/wikis/{wiki}/spaces

 

 返回： 

 200

 

 

 创建页面 

 接口： 

 PUT

/rest/wikis/xwiki/spaces/{space}/pages/{page}

 

 

 更新页面 

 同创建接口： 

 PUT

 

 XWiki自动判断： 

 新增

或者

版本更新

 

 

 删除页面 

 接口： 

 DELETE

/rest/wikis/xwiki/spaces/{space}/pages/{page}

 

 成功： 

 200

202

204

 

 不存在： 

 404

 

 均视为同步成功。 

 

 6. 数据库设计 

 数据库： 

 SQLite 

 用途： 

 保存同步状态。 

 主要字段： 

 

 

 

 字段 

 说明 

 

 

 

 

 file_path 

 文件路径 

 

 

 hash 

 文件SHA 

 

 

 space 

 XWiki空间 

 

 

 page 

 XWiki页面 

 

 

 deleted 

 删除状态 

 

 

 

 

 7. Docker部署 

 运行模式： 

 Docker Container

 

 容器： 

 xwiki-sync

 

 依赖： 

 xwiki-web

tika

smb共享

 

 网络： 

 Docker bridge

 

 

 8. 配置文件 

 文件： 

 config.yaml

 

 包含： 

 XWiki 

 例如： 

 xwiki:

 url: http://xwiki-web:8080

 wiki: xwiki

 user: admin

 password: ****

 

 

 SMB 

 例如： 

 smb:

 server:

 share:

 username:

 password:

 

 

 同步周期 

 例如： 

 interval: 60

 

 单位： 

 秒 

 

 9. 日志说明 

 正常： 

 发现文件 3 个

 

 新增： 

 新文件:

xxx

 

 跳过： 

 跳过:

xxx 未变化

 

 删除： 

 发现删除文件

删除XWiki页面

XWiki删除成功

 

 异常： 

 同步失败

 

 

 10. 已知设计特点 

 优点 

 1. 增量同步 

 不会重复处理大量文档。 

 2. 状态可恢复 

 数据库保存状态。 

 3. 支持中文名称 

 例如： 

 新建空间测试1

主从复制_2025030401

 

 4. XWiki自动版本管理 

 更新不会覆盖历史。 

 

 11. 当前限制 

 11.1 空间创建 

 目前： 

 create_space()

 

 XWiki REST 返回： 

 405 Method Not Allowed

 

 原因： 

 XWiki默认不允许REST创建Space。 

 当前策略： 

 忽略Space创建失败

继续创建页面

 

 实际运行正常。 

 

 11.2 删除空间 

 未实现。 

 删除： 

 页面

 

 不删除： 

 Space

 

 

 11.3 附件同步 

 当前： 

 文件内容同步

 

 不是： 

 XWiki Attachment

 

 

 12. 稳定性验证记录 

 新增测试 

 文件： 

 /data/wiki_attach/docker镜像导出和导入.txt

 

 结果： 

 同步完成

 

 

 删除测试 

 删除： 

 docker镜像导出和导入.txt

创建容器四代网关协议代理适配器rulr-v4gw-adapter.txt

 

 结果： 

 XWiki删除成功

 

 

 连续运行测试 

 周期： 

 60秒

 

 结果： 

 无重复同步

无异常

 

 

 13. 版本状态 

 当前版本： 

 xwiki-sync v1.0 Stable

 

 状态： 

 生产可用

 

 已验证： 

 

 

 

 功能 

 状态 

 

 

 

 

 新增同步 

 ✅ 

 

 

 修改同步 

 ✅ 

 

 

 删除同步 

 ✅ 

 

 

 中文路径 

 ✅ 

 

 

 中文页面 

 ✅ 

 

 

 DOCX解析 

 ✅ 

 

 

 TXT解析 

 ✅ 

 

 

 XWiki REST 

 ✅ 

 

 

 Docker运行 

 ✅ 

 

 

 断点恢复 

 ✅ 

 

 

 

 

 14. 后续规划建议 

 v1.1： 

 

 

 增加附件上传 

 

 

 增加XWiki标签 

 

 

 增加文档权限映射 

 

 

 增加同步失败重试队列 

 

 

 v1.2： 

 

 

 Web管理界面 

 

 

 同步状态监控 

 

 

 操作审计日志 

 

 

 

 结论 

 xwiki-sync v1.0 已完成共享目录到 XWiki 文档中心的自动化同步闭环。 

 当前版本满足： 

 

 企业内部文档自动归档、同步、删除管理需求。 

 

 可作为生产环境基础版本长期运行。 

 

 建议归档： 

 /opt/xwiki/sync/docs/

 |

 └── xwiki-sync-v1.0功能说明书.md

 

 同时建议备份： 

 config.yaml

database.db

Dockerfile

 

 作为 v1.0 基线版本。