# 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
例如：
```yaml
xwiki:
url: http://xwiki-web:8080
wiki: xwiki
user: admin
password: ****
```
---
## SMB
例如：
```yaml
smb:
server:
share:
username:
password:
```
---
## 同步周期
例如：
```yaml
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 基线版本。