112 lines
3.2 KiB
Markdown
112 lines
3.2 KiB
Markdown
# AGENTS.md
|
||
|
||
> 本项目（阿里云 VOD 媒体库管理器）的代理开发指南。
|
||
|
||
## 项目背景
|
||
|
||
一个轻量、开源、可自托管的阿里云视频点播（VOD）媒体资源管理后台。核心目标是解决阿里云官方 VOD 控制台在查看、批量下载、批量删除大量视频时操作繁琐的问题。
|
||
|
||
- 许可证：MIT
|
||
- 用户群体：开发者、内容运营人员
|
||
- 部署方式：Docker / 源码运行
|
||
|
||
## 技术栈
|
||
|
||
- **前端**：React 18 + TypeScript + Vite + Ant Design 5 + Zustand
|
||
- **后端**：Node.js 20 + Express + TypeScript + SQLite
|
||
- **阿里云 SDK**：`@alicloud/pop-core`
|
||
- **容器化**：Docker + Docker Compose
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
.
|
||
├── apps/
|
||
│ ├── web/ # React 前端
|
||
│ └── server/ # Express 后端
|
||
├── docker/
|
||
│ ├── Dockerfile
|
||
│ ├── docker-compose.yml
|
||
│ └── .env.example
|
||
├── docs/ # 部署与使用文档
|
||
├── PRD.md # 产品需求文档
|
||
├── README.md
|
||
└── AGENTS.md # 本文件
|
||
```
|
||
|
||
## 开发规范
|
||
|
||
### 代码风格
|
||
|
||
- 使用 TypeScript，严格模式开启。
|
||
- 后端统一使用 `asyncHandler` 包装异步路由处理器，避免未捕获异常导致进程崩溃。
|
||
- 后端数据库查询结果使用 camelCase 别名与 TypeScript 接口保持一致。
|
||
- 前端使用函数组件 + Hooks，状态管理使用 Zustand。
|
||
- API 响应统一格式：`{ code: number, data: T, message?: string }`。
|
||
|
||
### 安全要求
|
||
|
||
- AccessKey Secret 必须加密存储（`APP_ENCRYPTION_KEY`），生产环境必须设置。
|
||
- JWT 密钥生产环境必须修改，默认密钥不允许用于生产。
|
||
- 阿里云 API 调用仅在后端进行，禁止前端直接持有密钥。
|
||
- 建议用户创建最小权限 RAM 子用户。
|
||
|
||
### 环境变量
|
||
|
||
后端关键配置见 `apps/server/.env.example`：
|
||
|
||
- `PORT`：服务端端口
|
||
- `JWT_SECRET`：JWT 签名密钥
|
||
- `APP_ENCRYPTION_KEY`：AccessKey Secret 加密密钥
|
||
- `DEFAULT_ADMIN_USERNAME/PASSWORD`：默认管理员账号
|
||
- `DB_PATH`：SQLite 数据库路径
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 开发启动（同时启动前后端）
|
||
npm run dev
|
||
|
||
# 单独启动后端
|
||
npm run dev -w apps/server
|
||
|
||
# 单独启动前端
|
||
npm run dev -w apps/web
|
||
|
||
# 代码检查
|
||
npm run lint
|
||
|
||
# 测试
|
||
npm run test
|
||
|
||
# 生产构建
|
||
npm run build
|
||
|
||
# 生产运行
|
||
npm run start -w apps/server
|
||
```
|
||
|
||
## 后端路由约定
|
||
|
||
- `/api/auth`：登录与当前用户
|
||
- `/api/accounts`：阿里云账号配置（需管理员权限修改）
|
||
- `/api/videos`：视频列表、详情、批量下载/删除/更新
|
||
- `/api/categories`：VOD 分类树
|
||
- `/api/logs`：操作日志
|
||
|
||
## 数据库表
|
||
|
||
- `users`：用户表（id, username, password_hash, role, created_at）
|
||
- `accounts`：阿里云账号表（access_key_id, access_key_secret, region, endpoint, is_active, ...）
|
||
- `operation_logs`：操作日志表（action, target_type, target_ids, details, ...）
|
||
|
||
## 贡献注意事项
|
||
|
||
1. 修改前后端代码后，必须跑通 `npm run lint` 和 `npm run test`。
|
||
2. 后端新增接口建议同步写入 `docs/api.md`（如存在）。
|
||
3. 涉及数据库 schema 变更时，需考虑现有部署的兼容性。
|
||
4. 提交信息使用中文，描述清晰。
|