knowledge/ARCHITECTURE.md

企业级知识库 (EKB) 架构设计文档

本文档记录了项目设计阶段达成的所有高层架构决策与工作流。

🛠️ 技术栈清单 (已确认)

层级	技术选型	说明
前端框架	Next.js 15 (App Router), TypeScript, Tailwind CSS, shadcn/ui	全栈 React 框架，提供现代化的 UI 组件。
后端逻辑	Next.js Server Actions & Route Handlers	无状态逻辑设计，支持水平扩展。
数据库	PostgreSQL 16 + Drizzle ORM	高性能关系型数据库，负责结构化数据存储。
身份认证	Auth.js (NextAuth v5)	处理用户登录、Session 管理及身份提供商集成。
对象存储	MinIO (S3 兼容)	私有化部署，用于存储所有媒体文件和文档。
流媒体服务	SRS (Simple Realtime Server)	提供专业的 HLS/WebRTC 流媒体分发。
异步任务	Redis + BullMQ	处理转码、预处理等耗时后台任务的队列系统。
部署方式	手动脚本化部署 (systemd, Nginx)	高度可控，无 Docker 开销，便于调试和维护。

🔐 权限模型：双层级 RBAC + ACL

系统采用混合模式，平衡了组织架构的宏观管理与资源访问的微观控制。

1. 组织层级 (RBAC - 基于角色的访问控制)

逻辑: 用户 $\rightarrow$ 用户组 $\rightarrow$ 角色 $\rightarrow$ 权限

• 定义基于职能的宏观权限（例如：“编辑者”角色拥有“写入”权限）。

2. 资源层级 (ACL - 访问控制列表)

逻辑: 资源 (文件/文件夹) $\leftarrow$ 特定的 ACL 规则

• 允许针对特定文件或文件夹设置特殊的覆盖权限。
• 继承机制: 通过路径匹配实现文件夹权限向子资源的自动传递。
• 冲突解决策略: 拒绝优先 (Deny-Override) —— 任何显式的“拒绝”指令都具有最高优先级。

🎥 视频处理流水线

为了保证用户体验，所有媒体处理均采用异步非阻塞模式。

流程: 上传 $\rightarrow$ MinIO (原始文件) $\rightarrow$ BullMQ 队列 $\rightarrow$ FFmpeg Worker $\rightarrow$ SRS (HLS/WebRTC) $\rightarrow$ 前端播放

• 非阻塞设计: 用户在转码期间可以继续进行其他操作。
• 多分辨率支持: 自动生成 720p, 480p, 360p 等不同码率的流。
• 流畅体验: 通过 HLS 切片技术实现进度条的任意跳转和快速加载。

🚀 部署架构 (分布式单体)

服务器 1：应用层

• Next.js 应用实例 (通过 Nginx 进行负载均衡)
• Redis (用于 Session 和任务队列)
• Bull Workers (负责转码任务的后台进程)
• Nginx (反向代理与 SSL 卸载)

服务器 2：数据层

• PostgreSQL (主从架构)
• 自动化备份服务

服务器 3：存储与流媒体层

• MinIO 集群 (对象存储)
• SRS 服务 (流媒体引擎)
• 文件同步服务