kb-web/docs/requirements.md

kb-web 需求与设计文档

1. 项目概述

1.1 项目名称

kb-web（Knowledge Base Web）- 知识库网页系统

1.2 项目描述

kb-web 是一个基于 PHP 的知识库管理系统，用于展示和管理用户的知识库内容。系统支持从多种平台（Bilibili、YouTube、知乎等）采集的内容，并提供统一的浏览和搜索界面。

1.3 目标用户

• 个人用户：管理自己的知识库
• 团队用户：共享和管理团队知识资产

---

2. 功能需求

2.1 用户认证

功能	描述
用户登录	用户名 + 密码登录
会话管理	基于 PHP Session 的会话管理
登出功能	安全退出系统

2.2 文档管理

功能	描述
文档列表	分页展示所有文档
文档搜索	全文搜索文档内容
文档查看	在线阅读文档内容
目录结构	支持子目录分类展示

2.3 元数据展示

元数据	说明
标题	文档标题（从 YAML front matter 提取）
作者	内容作者
发布时间	原始内容发布时间
平台	来源平台（Bilibili、YouTube、知乎等）
标签	内容标签
时长	视频时长（仅视频类型）
类型	文章 / 视频
源链接	原始内容链接

2.4 界面功能

功能	描述
响应式设计	支持桌面和移动设备
暗色主题	科技感暗色界面
搜索高亮	搜索结果关键词高亮
Markdown 渲染	支持基本 Markdown 语法

---

3. 技术架构

3.1 技术栈

层级	技术
前端	HTML5, CSS3, JavaScript
后端	PHP 8.0+
数据库	MySQL 5.7+
Web 服务器	Nginx
部署	Git + CI/CD (Gitea Actions)

3.2 目录结构

kb-web/
├── index.php          # 登录页
├── dashboard.php      # 文档列表页
├── view.php           # 文档查看页
├── config.php         # 配置文件（不纳入版本控制）
├── config.test.php    # 测试环境配置模板
├── style.css          # 样式文件
├── logout.php         # 登出处理
├── add_user.php       # 用户添加
├── init.sql           # 数据库初始化脚本
├── docs/              # 文档目录
│   └── requirements.md
├── deploy/            # 部署脚本
│   ├── deploy.sh
│   ├── setup-server.sh
│   └── webhook-receiver.php
├── tests/             # 测试文件
│   ├── bootstrap.php
│   ├── Unit/
│   └── Feature/
├── .gitea/            # CI/CD 配置
│   └── workflows/
│       └── ci.yml
├── .gitignore
├── composer.json
├── phpunit.xml
└── README.md

3.3 数据库设计

用户表 (users)

字段	类型	说明
id	INT	主键，自增
username	VARCHAR(50)	用户名，唯一
password_hash	VARCHAR(255)	密码哈希
created_at	TIMESTAMP	创建时间

3.4 文件存储结构

用户目录/
├── 用户名1/
│   ├── analyzed/      # 分析后的 Markdown 文件
│   ├── metadata/      # 元数据 JSON 文件
│   ├── content/       # 原始内容文件
│   └── pending/       # 待处理文件
└── 用户名2/
    └── ...

---

4. 页面设计

4.1 登录页 (index.php)

功能：

• 用户名密码输入
• 错误提示
• 登录验证

设计特点：

• 居中登录框
• 渐变背景 + 旋转光效
• 玻璃拟态卡片
• 品牌标题 "知识库"

4.2 文档列表页 (dashboard.php)

功能：

• 搜索栏
• 文档统计
• 文档卡片列表
• 用户信息显示

卡片信息展示：

• 平台图标
• 类型图标
• 标题
• 作者、发布时间、平台、时长
• 标签（最多5个）
• 源链接
• 概述（前两行）

4.3 文档查看页 (view.php)

功能：

• 返回列表
• 元数据卡片
• Markdown 内容渲染
• 搜索高亮

元数据卡片：

• 作者
• 发布时间
• 平台（彩色徽章）
• 时长
• 类型
• 源链接
• 标签列表

---

5. CI/CD 流程

5.1 部署流程

┌─────────────────────────────────────────────────────────────┐
│  feature/* 分支 push                                         │
│        │                                                     │
│        ▼                                                     │
│  自动部署到测试环境 (http://micecola.top:8081)               │
│        │                                                     │
│        ▼                                                     │
│  运行测试                                                    │
│        │ 通过                                                │
│        ▼                                                     │
│  自动合并到 main                                             │
│        │                                                     │
│        ▼                                                     │
│  ⏸️ 等待手动确认...                                          │
│        │                                                     │
│        ▼ 手动触发                                            │
│  部署到正式环境 (http://micecola.top)                        │
└─────────────────────────────────────────────────────────────┘

5.2 环境配置

环境	域名	目录	触发方式
测试	http://micecola.top:8081	/www/wwwroot/kb-web-test	自动
正式	http://micecola.top	/www/wwwroot/kb-web	手动

5.3 部署特性

• ✅ 配置文件保护（config.php 不被覆盖）
• ✅ 自动备份（保留最近5个版本）
• ✅ 版本回滚支持
• ✅ 环境隔离

---

6. 样式规范

6.1 色彩系统

名称	色值	用途
背景深色	#0a0e17	页面背景
背景表面	#111827	卡片背景
强调色-青	#38bdf8	主色调、链接
强调色-紫	#a855f7	辅助强调
强调色-绿	#22c55e	成功状态
文字主色	#f1f5f9	主要文字
文字次色	#94a3b8	次要文字

6.2 平台颜色

平台	色值
Bilibili	#fb7299
YouTube	#ff0000
知乎	#0084ff
微信	#07c160

6.3 字体

用途	字体
正文	Space Grotesk
代码	JetBrains Mono

---

7. 安全设计

7.1 已实现

安全措施	说明
密码哈希	使用 password_hash()
SQL 注入防护	PDO 预处理语句
XSS 防护	htmlspecialchars()
目录遍历防护	路径检查
会话管理	PHP Session

7.2 待加强

• CSRF 防护
• 登录失败次数限制
• HTTPS 强制
• 密码强度验证

---

8. 扩展计划

8.1 短期计划

• 分页功能
• 标签筛选
• 收藏功能
• 阅读进度记录

8.2 长期计划

• 多用户协作
• 权限管理
• API 接口
• 移动端 App
• 全文搜索优化（Elasticsearch）

---

9. 依赖项目

9.1 关联仓库

仓库	说明
kb-skills	内容处理技能模块
knowledge-base	知识库内容存储

9.2 知识库同步

knowledge-base 仓库独立部署，自动同步到用户目录：

• 测试环境：/www/wwwroot/kb-web-test/zhangqing/
• 正式环境：/www/wwwroot/kb-web/zhangqing/

---

10. 维护说明

10.1 日志位置

日志	路径
Nginx 访问日志	/www/wwwlogs/micecola.top.log
Nginx 错误日志	/www/wwwlogs/micecola.top.error.log
部署日志	/var/log/kb-web-deploy.log
备份目录	/www/backup/kb-web/

10.2 常用命令

# 手动部署测试环境
cd /www/wwwroot/kb-web-test && git pull origin main

# 手动部署正式环境
cd /www/wwwroot/kb-web && git pull origin main

# 查看备份
ls /www/backup/kb-web/

# 回滚到备份版本
tar -xzf /www/backup/kb-web/backup_XXX.tar.gz -C /www/wwwroot/kb-web/

---

11. 版本历史

版本	日期	变更内容
1.0.0	2026-02-13	初始版本，基础功能
1.1.0	2026-02-15	暗色科技感风格改造
1.2.0	2026-02-15	CI/CD 自动部署
1.3.0	2026-02-15	元数据展示优化，标签支持

---

文档最后更新：2026-02-15