342 lines
14 KiB
Markdown
342 lines
14 KiB
Markdown
# NEX Docus 数据库设计文档
|
||
|
||
## 数据库连接信息
|
||
- **数据库类型**: MySQL 5.7.5+
|
||
- **连接地址**: 10.100.51.51:3306
|
||
- **数据库名**: nex_docus
|
||
- **字符集**: utf8mb4
|
||
- **排序规则**: utf8mb4_unicode_ci
|
||
|
||
## Redis 缓存
|
||
- **连接地址**: 10.100.51.51:6379
|
||
- **用途**: Session 存储、Token 黑名单、文件上传临时缓存
|
||
|
||
---
|
||
|
||
## 1. 用户认证相关表
|
||
|
||
### 1.1 用户表 (`users`)
|
||
|
||
存储系统用户基本信息。
|
||
|
||
```sql
|
||
CREATE TABLE `users` (
|
||
`id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '用户ID',
|
||
`username` VARCHAR(50) NOT NULL UNIQUE COMMENT '用户名（登录账号）',
|
||
`password_hash` VARCHAR(255) NOT NULL COMMENT '密码哈希（bcrypt）',
|
||
`nickname` VARCHAR(50) DEFAULT NULL COMMENT '昵称（显示名称）',
|
||
`email` VARCHAR(100) DEFAULT NULL COMMENT '邮箱',
|
||
`phone` VARCHAR(20) DEFAULT NULL COMMENT '手机号',
|
||
`avatar` VARCHAR(255) DEFAULT NULL COMMENT '头像URL',
|
||
`status` TINYINT DEFAULT 1 COMMENT '状态：0-禁用 1-启用',
|
||
`is_superuser` TINYINT DEFAULT 0 COMMENT '是否超级管理员：0-否 1-是',
|
||
`last_login_at` DATETIME DEFAULT NULL COMMENT '最后登录时间',
|
||
`last_login_ip` VARCHAR(50) DEFAULT NULL COMMENT '最后登录IP',
|
||
`created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
`updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||
INDEX `idx_username` (`username`),
|
||
INDEX `idx_email` (`email`),
|
||
INDEX `idx_status` (`status`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';
|
||
```
|
||
|
||
### 1.2 角色表 (`roles`)
|
||
|
||
定义系统角色。
|
||
|
||
```sql
|
||
CREATE TABLE `roles` (
|
||
`id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '角色ID',
|
||
`role_name` VARCHAR(50) NOT NULL UNIQUE COMMENT '角色名称',
|
||
`role_code` VARCHAR(50) NOT NULL UNIQUE COMMENT '角色编码（如：admin, editor, viewer）',
|
||
`description` VARCHAR(255) DEFAULT NULL COMMENT '角色描述',
|
||
`status` TINYINT DEFAULT 1 COMMENT '状态：0-禁用 1-启用',
|
||
`is_system` TINYINT DEFAULT 0 COMMENT '是否系统角色：0-否 1-是（系统角色不可删除）',
|
||
`created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
`updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||
INDEX `idx_role_code` (`role_code`),
|
||
INDEX `idx_status` (`status`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='角色表';
|
||
```
|
||
|
||
**预置角色数据**:
|
||
```sql
|
||
INSERT INTO `roles` (`role_name`, `role_code`, `description`, `is_system`) VALUES
|
||
('超级管理员', 'super_admin', '拥有系统所有权限', 1),
|
||
('项目管理员', 'project_admin', '可以创建和管理项目', 1),
|
||
('普通用户', 'user', '可以查看和编辑被授权的项目', 1),
|
||
('访客', 'guest', '只读权限', 1);
|
||
```
|
||
|
||
### 1.3 用户角色关联表 (`user_roles`)
|
||
|
||
用户与角色多对多关系。
|
||
|
||
```sql
|
||
CREATE TABLE `user_roles` (
|
||
`id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '关联ID',
|
||
`user_id` BIGINT NOT NULL COMMENT '用户ID',
|
||
`role_id` BIGINT NOT NULL COMMENT '角色ID',
|
||
`created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
UNIQUE KEY `uk_user_role` (`user_id`, `role_id`),
|
||
INDEX `idx_user_id` (`user_id`),
|
||
INDEX `idx_role_id` (`role_id`),
|
||
FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE CASCADE,
|
||
FOREIGN KEY (`role_id`) REFERENCES `roles`(`id`) ON DELETE CASCADE
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户角色关联表';
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 权限与菜单管理
|
||
|
||
### 2.1 系统菜单表 (`system_menus`)
|
||
|
||
定义系统功能菜单和权限点。
|
||
|
||
```sql
|
||
CREATE TABLE `system_menus` (
|
||
`id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '菜单ID',
|
||
`parent_id` BIGINT DEFAULT 0 COMMENT '父菜单ID（0表示根菜单）',
|
||
`menu_name` VARCHAR(50) NOT NULL COMMENT '菜单名称',
|
||
`menu_code` VARCHAR(50) NOT NULL UNIQUE COMMENT '菜单编码（权限标识）',
|
||
`menu_type` TINYINT NOT NULL COMMENT '菜单类型：1-目录 2-菜单 3-按钮/权限点',
|
||
`path` VARCHAR(255) DEFAULT NULL COMMENT '路由路径',
|
||
`component` VARCHAR(255) DEFAULT NULL COMMENT '组件路径',
|
||
`icon` VARCHAR(100) DEFAULT NULL COMMENT '图标',
|
||
`sort_order` INT DEFAULT 0 COMMENT '排序号',
|
||
`visible` TINYINT DEFAULT 1 COMMENT '是否可见：0-隐藏 1-显示',
|
||
`status` TINYINT DEFAULT 1 COMMENT '状态：0-禁用 1-启用',
|
||
`permission` VARCHAR(100) DEFAULT NULL COMMENT '权限字符串（如：project:create）',
|
||
`created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
`updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||
INDEX `idx_parent_id` (`parent_id`),
|
||
INDEX `idx_menu_code` (`menu_code`),
|
||
INDEX `idx_status` (`status`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统菜单表';
|
||
```
|
||
|
||
**预置菜单数据**:
|
||
```sql
|
||
INSERT INTO `system_menus` (`id`, `parent_id`, `menu_name`, `menu_code`, `menu_type`, `path`, `icon`, `sort_order`, `permission`) VALUES
|
||
(1, 0, '项目管理', 'project', 1, '/projects', 'FolderOutlined', 1, NULL),
|
||
(2, 1, '我的项目', 'my_projects', 2, '/projects/my', NULL, 1, 'project:view'),
|
||
(3, 1, '创建项目', 'create_project', 3, NULL, NULL, 2, 'project:create'),
|
||
(4, 1, '编辑项目', 'edit_project', 3, NULL, NULL, 3, 'project:edit'),
|
||
(5, 1, '删除项目', 'delete_project', 3, NULL, NULL, 4, 'project:delete'),
|
||
(10, 0, '文档管理', 'document', 1, '/documents', 'FileTextOutlined', 2, NULL),
|
||
(11, 10, '查看文档', 'view_document', 3, NULL, NULL, 1, 'document:view'),
|
||
(12, 10, '编辑文档', 'edit_document', 3, NULL, NULL, 2, 'document:edit'),
|
||
(13, 10, '删除文档', 'delete_document', 3, NULL, NULL, 3, 'document:delete'),
|
||
(20, 0, '系统管理', 'system', 1, '/system', 'SettingOutlined', 3, NULL),
|
||
(21, 20, '用户管理', 'user_manage', 2, '/system/users', NULL, 1, 'system:user:view'),
|
||
(22, 20, '角色管理', 'role_manage', 2, '/system/roles', NULL, 2, 'system:role:view');
|
||
```
|
||
|
||
### 2.2 角色菜单授权表 (`role_menus`)
|
||
|
||
角色与菜单权限的多对多关系。
|
||
|
||
```sql
|
||
CREATE TABLE `role_menus` (
|
||
`id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '关联ID',
|
||
`role_id` BIGINT NOT NULL COMMENT '角色ID',
|
||
`menu_id` BIGINT NOT NULL COMMENT '菜单ID',
|
||
`created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
UNIQUE KEY `uk_role_menu` (`role_id`, `menu_id`),
|
||
INDEX `idx_role_id` (`role_id`),
|
||
INDEX `idx_menu_id` (`menu_id`),
|
||
FOREIGN KEY (`role_id`) REFERENCES `roles`(`id`) ON DELETE CASCADE,
|
||
FOREIGN KEY (`menu_id`) REFERENCES `system_menus`(`id`) ON DELETE CASCADE
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='角色菜单授权表';
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 项目与文档管理
|
||
|
||
### 3.1 项目表 (`projects`)
|
||
|
||
存储项目基本信息。
|
||
|
||
```sql
|
||
CREATE TABLE `projects` (
|
||
`id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '项目ID',
|
||
`name` VARCHAR(100) NOT NULL COMMENT '项目名称',
|
||
`description` VARCHAR(500) DEFAULT NULL COMMENT '项目描述',
|
||
`storage_key` CHAR(36) NOT NULL COMMENT '磁盘存储UUID（物理文件夹名）',
|
||
`owner_id` BIGINT NOT NULL COMMENT '项目所有者ID',
|
||
`is_public` TINYINT DEFAULT 0 COMMENT '是否公开：0-私有 1-公开',
|
||
`is_template` TINYINT DEFAULT 0 COMMENT '是否模板项目：0-否 1-是',
|
||
`status` TINYINT DEFAULT 1 COMMENT '状态：0-归档 1-活跃',
|
||
`cover_image` VARCHAR(255) DEFAULT NULL COMMENT '封面图',
|
||
`sort_order` INT DEFAULT 0 COMMENT '排序号',
|
||
`visit_count` INT DEFAULT 0 COMMENT '访问次数',
|
||
`git_repo_url` VARCHAR(255) DEFAULT NULL COMMENT 'Git仓库地址',
|
||
`git_branch` VARCHAR(50) DEFAULT 'main' COMMENT 'Git分支',
|
||
`git_username` VARCHAR(100) DEFAULT NULL COMMENT 'Git用户名',
|
||
`git_token` VARCHAR(255) DEFAULT NULL COMMENT 'Git访问令牌/密码',
|
||
`created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
`updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||
UNIQUE KEY `uk_storage_key` (`storage_key`),
|
||
INDEX `idx_owner_id` (`owner_id`),
|
||
INDEX `idx_name` (`name`),
|
||
INDEX `idx_status` (`status`),
|
||
INDEX `idx_created_at` (`created_at`),
|
||
FOREIGN KEY (`owner_id`) REFERENCES `users`(`id`) ON DELETE CASCADE
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='项目表';
|
||
```
|
||
|
||
### 3.2 项目成员表 (`project_members`)
|
||
|
||
项目协作成员管理。
|
||
|
||
```sql
|
||
CREATE TABLE `project_members` (
|
||
`id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '成员ID',
|
||
`project_id` BIGINT NOT NULL COMMENT '项目ID',
|
||
`user_id` BIGINT NOT NULL COMMENT '用户ID',
|
||
`role` ENUM('admin', 'editor', 'viewer') DEFAULT 'viewer' COMMENT '项目角色：admin-管理员 editor-编辑者 viewer-查看者',
|
||
`invited_by` BIGINT DEFAULT NULL COMMENT '邀请人ID',
|
||
`joined_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '加入时间',
|
||
UNIQUE KEY `uk_project_user` (`project_id`, `user_id`),
|
||
INDEX `idx_project_id` (`project_id`),
|
||
INDEX `idx_user_id` (`user_id`),
|
||
INDEX `idx_role` (`role`),
|
||
FOREIGN KEY (`project_id`) REFERENCES `projects`(`id`) ON DELETE CASCADE,
|
||
FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE CASCADE,
|
||
FOREIGN KEY (`invited_by`) REFERENCES `users`(`id`) ON DELETE SET NULL
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='项目成员表';
|
||
```
|
||
|
||
### 3.3 文档元数据表 (`document_meta`)
|
||
|
||
可选表，用于存储文档的额外元数据（标签、评论数等）。
|
||
|
||
```sql
|
||
CREATE TABLE `document_meta` (
|
||
`id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '元数据ID',
|
||
`project_id` BIGINT NOT NULL COMMENT '项目ID',
|
||
`file_path` VARCHAR(500) NOT NULL COMMENT '文件相对路径',
|
||
`title` VARCHAR(200) DEFAULT NULL COMMENT '文档标题',
|
||
`tags` VARCHAR(500) DEFAULT NULL COMMENT '标签（JSON数组）',
|
||
`author_id` BIGINT DEFAULT NULL COMMENT '作者ID',
|
||
`word_count` INT DEFAULT 0 COMMENT '字数统计',
|
||
`view_count` INT DEFAULT 0 COMMENT '浏览次数',
|
||
`last_editor_id` BIGINT DEFAULT NULL COMMENT '最后编辑者ID',
|
||
`last_edited_at` DATETIME DEFAULT NULL COMMENT '最后编辑时间',
|
||
`created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
`updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||
UNIQUE KEY `uk_project_path` (`project_id`, `file_path`),
|
||
INDEX `idx_project_id` (`project_id`),
|
||
INDEX `idx_author_id` (`author_id`),
|
||
FULLTEXT KEY `ft_title_tags` (`title`, `tags`),
|
||
FOREIGN KEY (`project_id`) REFERENCES `projects`(`id`) ON DELETE CASCADE,
|
||
FOREIGN KEY (`author_id`) REFERENCES `users`(`id`) ON DELETE SET NULL,
|
||
FOREIGN KEY (`last_editor_id`) REFERENCES `users`(`id`) ON DELETE SET NULL
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文档元数据表';
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 操作日志与审计
|
||
|
||
### 4.1 操作日志表 (`operation_logs`)
|
||
|
||
记录关键操作日志。
|
||
|
||
```sql
|
||
CREATE TABLE `operation_logs` (
|
||
`id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '日志ID',
|
||
`user_id` BIGINT DEFAULT NULL COMMENT '操作用户ID',
|
||
`username` VARCHAR(50) DEFAULT NULL COMMENT '用户名（冗余字段）',
|
||
`operation_type` VARCHAR(50) NOT NULL COMMENT '操作类型（create, update, delete等）',
|
||
`resource_type` VARCHAR(50) NOT NULL COMMENT '资源类型（project, document, user等）',
|
||
`resource_id` BIGINT DEFAULT NULL COMMENT '资源ID',
|
||
`detail` TEXT DEFAULT NULL COMMENT '操作详情（JSON）',
|
||
`ip_address` VARCHAR(50) DEFAULT NULL COMMENT 'IP地址',
|
||
`user_agent` VARCHAR(500) DEFAULT NULL COMMENT '用户代理',
|
||
`status` TINYINT DEFAULT 1 COMMENT '状态：0-失败 1-成功',
|
||
`error_message` TEXT DEFAULT NULL COMMENT '错误信息',
|
||
`created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '操作时间',
|
||
INDEX `idx_user_id` (`user_id`),
|
||
INDEX `idx_resource` (`resource_type`, `resource_id`),
|
||
INDEX `idx_created_at` (`created_at`),
|
||
FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE SET NULL
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='操作日志表';
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 文件存储说明
|
||
|
||
### 5.1 物理存储结构
|
||
|
||
**根目录**: `/data/nex_docus_store/`
|
||
|
||
```
|
||
/data/nex_docus_store/
|
||
├── projects/
|
||
│ ├── <project_uuid>/ # 项目文件夹（UUID命名）
|
||
│ │ ├── README.md # 项目首页
|
||
│ │ ├── _assets/ # 资源文件夹（图片、附件）
|
||
│ │ │ ├── images/ # 图片
|
||
│ │ │ └── files/ # 附件
|
||
│ │ ├── <folder>/ # 用户创建的文件夹
|
||
│ │ │ └── *.md # Markdown文档
|
||
│ │ └── ...
|
||
└── temp/ # 临时文件（上传缓存）
|
||
```
|
||
|
||
### 5.2 存储规则
|
||
|
||
1. **项目隔离**: 每个项目使用独立的 UUID 文件夹
|
||
2. **路径映射**: `storage_key` 字段存储 UUID，数据库存储显示名称
|
||
3. **资源管理**: 图片和附件存储在 `_assets` 目录
|
||
4. **安全控制**: 所有文件访问必须经过权限验证
|
||
5. **备份策略**: 可直接备份 `/data/nex_docus_store/` 目录
|
||
|
||
---
|
||
|
||
## 6. 索引优化建议
|
||
|
||
1. **复合索引**:
|
||
- `projects`: (`owner_id`, `status`)
|
||
- `project_members`: (`project_id`, `role`)
|
||
- `document_meta`: (`project_id`, `last_edited_at`)
|
||
|
||
2. **覆盖索引**: 针对高频查询添加包含查询字段的复合索引
|
||
|
||
3. **分区表**: 当 `operation_logs` 数据量大时，可按月份分区
|
||
|
||
---
|
||
|
||
## 7. 数据库初始化脚本
|
||
|
||
创建完整的初始化 SQL 文件：`backend/scripts/init_database.sql`
|
||
|
||
执行顺序：
|
||
1. 创建数据库
|
||
2. 创建所有表
|
||
3. 插入初始角色数据
|
||
4. 插入初始菜单数据
|
||
5. 创建默认管理员用户
|
||
|
||
---
|
||
|
||
## 8. 性能优化建议
|
||
|
||
1. **连接池配置**: SQLAlchemy 配置合理的连接池大小
|
||
2. **查询优化**: 使用 `joinedload` 避免 N+1 查询
|
||
3. **缓存策略**:
|
||
- 用户信息缓存（5分钟）
|
||
- 菜单权限缓存（10分钟）
|
||
- 项目列表缓存（1分钟）
|
||
4. **读写分离**: 后续可配置主从数据库
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0
|
||
**最后更新**: 2023-12-20
|
||
**维护人**: Mula.liu
|