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 | 支持 |
| 支持 | |
| 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 基线版本。
No Comments