Aliyun-VOD-Media-Library-Manager/AGENTS.md

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 数据库路径

常用命令

# 安装依赖
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. 提交信息使用中文，描述清晰。