mula
/
nex_docus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
nex_docus/DATABASE.md

342 lines
14 KiB
Markdown
Raw Normal View History

0.9.1
2025-12-20 11:18:59 +00:00
# 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仓库管理
2026-01-05 10:50:29 +00:00
`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访问令牌/密码',
0.9.1
2025-12-20 11:18:59 +00:00
`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