307 lines
13 KiB
Markdown
307 lines
13 KiB
Markdown
# Eternal AI
|
||
|
||
AI 陪伴平台 — 人设创作者设定并发布角色，自动生成 Hermes Agent 可用的配置文件（SOUL.md + config.yaml），支持跨机器 CLI 拉取部署。
|
||
|
||
## 架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ 浏览器 (SPA) │
|
||
│ index.html + app.js + styles.css │
|
||
│ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌───────────┐ │
|
||
│ │ 认证视图 │ │ 角色库 │ │ 创作者中心 │ │ 角色编辑器 │ │
|
||
│ └──────────┘ └──────────┘ └───────────┘ └───────────┘ │
|
||
└──────────────────────┬───────────────────────────────────┘
|
||
│ HTTP / JSON
|
||
┌──────────────────────▼───────────────────────────────────┐
|
||
│ Express.js 服务端 (server.js) │
|
||
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌───────────────┐ │
|
||
│ │ /api/auth│ │/api/roles│ │/api/apikeys│ │ /api/hermes │ │
|
||
│ └────┬────┘ └────┬────┘ └─────┬────┘ └──────┬────────┘ │
|
||
│ │ │ │ │ │
|
||
│ ┌────▼───────────▼────────────▼──────────────▼────────┐ │
|
||
│ │ 认证中间件 (src/lib/auth.js) │ │
|
||
│ │ JWT 认证 (authMiddleware) + API Key 认证 │ │
|
||
│ │ (apiKeyMiddleware, eak_ 前缀, SHA-256 哈希) │ │
|
||
│ └─────────────────────┬───────────────────────────────┘ │
|
||
└────────────────────────┼─────────────────────────────────┘
|
||
│ Prisma ORM
|
||
┌────────────────────────▼─────────────────────────────────┐
|
||
│ PostgreSQL 数据库 │
|
||
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
|
||
│ │ User │ │ Role │ │ ApiKey │ │ Order │ │
|
||
│ └────────┘ └────────┘ └────────┘ └────────┘ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 技术栈
|
||
|
||
| 层 | 技术 |
|
||
|----|------|
|
||
| 前端 | 原生 HTML5 SPA（IIFE 模式，无框架）、玻璃拟态 UI |
|
||
| 后端 | Node.js + Express 5.x |
|
||
| 数据库 | PostgreSQL 15 + Prisma ORM 5.x |
|
||
| 认证 | JWT（7 天有效期）+ API Key（`eak_` 前缀，SHA-256 哈希存储） |
|
||
| 密码 | bcryptjs（10 轮盐） |
|
||
| 测试 | Playwright E2E（35 个测试用例） |
|
||
| 部署 | PM2 + Nginx 反向代理 |
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
EternalAI/
|
||
├── server.js # Express 入口，注册路由 + 静态文件
|
||
├── app.js # 前端 SPA 逻辑（路由、状态、表单、API 调用）
|
||
├── index.html # 单页应用入口（9 个视图）
|
||
├── styles.css # 玻璃拟态样式
|
||
├── prisma/
|
||
│ └── schema.prisma # 数据模型定义（User / Role / ApiKey / Order）
|
||
├── src/
|
||
│ ├── lib/
|
||
│ │ ├── auth.js # JWT + API Key 认证中间件
|
||
│ │ └── prisma.js # Prisma Client 单例
|
||
│ └── routes/
|
||
│ ├── auth.js # 注册 / 登录 / 用户信息 / 设置
|
||
│ ├── roles.js # 角色 CRUD + 角色库
|
||
│ ├── apikeys.js # API Key 生成 / 列表 / 删除
|
||
│ └── hermes.js # Hermes 配置拉取端点（SOUL.md / config.yaml）
|
||
├── deploy/
|
||
│ ├── setup-server.sh # 服务器一键初始化脚本
|
||
│ ├── deploy.sh # CI/CD 部署脚本
|
||
│ └── nginx.conf # Nginx 反向代理配置
|
||
├── e2e/ # Playwright E2E 测试
|
||
├── docs/ # 需求文档与规划
|
||
└── package.json
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 1. 安装依赖
|
||
npm install
|
||
|
||
# 2. 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env，设置 DATABASE_URL 和 JWT_SECRET
|
||
# JWT_SECRET 可用 openssl rand -hex 32 生成
|
||
|
||
# 3. 初始化数据库
|
||
npx prisma db push
|
||
npx prisma generate
|
||
|
||
# 4. 启动开发服务器
|
||
npm run dev
|
||
# → http://localhost:3001
|
||
```
|
||
|
||
### 服务器部署
|
||
|
||
```bash
|
||
# 在服务器上执行一键初始化脚本
|
||
bash deploy/setup-server.sh
|
||
# 自动安装 Node.js / PostgreSQL / Nginx / PM2，创建 .env，推送 Schema
|
||
```
|
||
|
||
## 操作流程
|
||
|
||
### 1. 用户注册与登录
|
||
|
||
```
|
||
用户 → 首页 → 登录/注册视图
|
||
├─ 注册：填写账号 + 密码（≥6位）→ 自动登录，返回 JWT
|
||
└─ 登录：账号 + 密码 → 验证成功，返回 JWT
|
||
└─ JWT 存入 localStorage，后续请求携带 Authorization: Bearer <token>
|
||
```
|
||
|
||
### 2. 创作者入驻与角色设定
|
||
|
||
```
|
||
登录用户 → 创作者入驻页 → 开通创作者身份
|
||
→ 创作者管理中心（三个 Tab）
|
||
├─ 角色 Tab：新建 / 编辑角色
|
||
├─ 收入 Tab：余额 + 付费流水
|
||
└─ 设置 Tab：昵称 / 角色库名 / API Key 管理
|
||
|
||
新建角色（4 步表单）：
|
||
Step 1 → 基础信息（名称、性别、年龄、关系）
|
||
Step 2 → 性格设定（性格、背景、说话风格、喜好）
|
||
Step 3 → 模型配置（模型、温度、最大 Token、记忆/工具开关）
|
||
Step 4 → 发布设置（问候语、价格、描述）
|
||
→ 提交后自动生成 SOUL.md + config.yaml 存入数据库
|
||
→ 角色上架到角色库
|
||
```
|
||
|
||
### 3. 角色库浏览与购买
|
||
|
||
```
|
||
任意用户 → 角色库 → 浏览已上架角色
|
||
→ 点击角色卡片 → 查看详情
|
||
→ 付款 → 创建订单 → 解锁角色
|
||
```
|
||
|
||
## 与 Hermes Agent 交互流程
|
||
|
||
EternalAI 生成的角色配置（SOUL.md + config.yaml）可通过 CLI 拉取命令部署到任意 Hermes Agent 机器上，支持跨机器部署。
|
||
|
||
### 架构图
|
||
|
||
```
|
||
服务器 A (EternalAI) 服务器 B (Hermes Agent)
|
||
┌───────────────────────┐ ┌───────────────────────┐
|
||
│ 1. 设置页生成 API Key │ │ │
|
||
│ (eak_xxxxxxxxxx) │ │ 5. hermes profile │
|
||
│ │ │ create role-mio │
|
||
│ 2. 创建角色 → 发布 │ │ │
|
||
│ 生成 SOUL.md + │ │ 6. curl 拉取文件 │
|
||
│ config.yaml │ │ SOUL.md │
|
||
│ │ │ config.yaml │
|
||
│ 3. 角色管理页显示 │ 4. 用户复制 │ │
|
||
│ curl 命令模板 │──── curl ────▶│ 7. 配置 .env │
|
||
│ (含 API Key) │ 命令执行 │ (API 密钥) │
|
||
│ │ │ │
|
||
│ │ │ 8. role-mio chat │
|
||
└───────────────────────┘ └───────────────────────┘
|
||
```
|
||
|
||
### 步骤详解
|
||
|
||
#### Step 1-3：在 EternalAI Web UI 操作
|
||
|
||
1. **生成 API Key**：创作者管理中心 → 设置 Tab → 点击「生成 API Key」→ 明文 Key 仅显示一次，请妥善保存
|
||
2. **创建角色**：创作者管理中心 → 角色 Tab → 新建角色 → 填写 4 步表单 → 发布
|
||
3. **获取部署命令**：角色卡片点击「Hermes 部署」→ 弹窗显示完整的 curl 命令模板（含服务器地址、角色 ID、API Key）→ 点击复制
|
||
|
||
#### Step 4-8：在 Hermes Agent 机器上操作
|
||
|
||
```bash
|
||
# 4. 复制 curl 命令到 Hermes 机器执行
|
||
|
||
# 5. 创建 Hermes profile
|
||
hermes profile create role-mio
|
||
|
||
# 6. 拉取 SOUL.md
|
||
curl -H "Authorization: Bearer eak_xxx" \
|
||
https://your-eternalai-domain.com/api/hermes/roles/<role-id>/SOUL.md \
|
||
-o ~/.hermes/profiles/role-mio/SOUL.md
|
||
|
||
# 7. 拉取 config.yaml
|
||
curl -H "Authorization: Bearer eak_xxx" \
|
||
https://your-eternalai-domain.com/api/hermes/roles/<role-id>/config.yaml \
|
||
-o ~/.hermes/profiles/role-mio/config.yaml
|
||
|
||
# 8. 配置 API 密钥并启动
|
||
echo "OPENROUTER_API_KEY=sk-or-xxx" > ~/.hermes/profiles/role-mio/.env
|
||
role-mio chat
|
||
```
|
||
|
||
### config.yaml 格式适配
|
||
|
||
EternalAI 角色数据自动转换为 Hermes config.yaml 格式：
|
||
|
||
| EternalAI 字段 | Hermes config.yaml 字段 |
|
||
|---|---|
|
||
| `role.model` | `model:` |
|
||
| `role.temperature` | `temperature:` |
|
||
| `role.maxTokens` | `max_tokens:` |
|
||
| `role.enableMemory` | `memory.enabled:` |
|
||
| `role.enableTools` | `tools.enabled:` |
|
||
|
||
生成的 config.yaml 示例：
|
||
|
||
```yaml
|
||
# Hermes Agent Config — generated by EternalAI
|
||
# Character: Mio
|
||
# Agent ID: default
|
||
# Generated at: 2026-06-21T12:00:00.000Z
|
||
|
||
model: "gpt-4o"
|
||
temperature: 0.85
|
||
max_tokens: 2048
|
||
|
||
memory:
|
||
enabled: true
|
||
storage: local
|
||
|
||
tools:
|
||
enabled: true
|
||
toolsets:
|
||
- memory
|
||
|
||
terminal:
|
||
backend: local
|
||
```
|
||
|
||
### API Key 安全机制
|
||
|
||
- **格式**：`eak_` + 32 位随机 hex（128 位熵）
|
||
- **存储**：SHA-256 哈希存储，明文仅在生成时返回一次
|
||
- **脱敏显示**：列表中仅显示前 12 位（如 `eak_a1b2c3d4`）
|
||
- **认证**：通过 `Authorization: Bearer eak_xxx` 头传递
|
||
- **权限**：API Key 只能拉取所属用户创建的角色配置
|
||
- **可吊销**：随时在设置页删除，删除后立即失效
|
||
|
||
## API 参考
|
||
|
||
### 认证 API
|
||
|
||
| 方法 | 路径 | 认证 | 说明 |
|
||
|------|------|------|------|
|
||
| POST | `/api/auth/register` | 无 | 注册（账号 + 密码） |
|
||
| POST | `/api/auth/login` | 无 | 登录 |
|
||
| GET | `/api/auth/me` | JWT | 获取当前用户信息 |
|
||
| PUT | `/api/auth/settings` | JWT | 更新用户设置 |
|
||
|
||
### 角色 API
|
||
|
||
| 方法 | 路径 | 认证 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/api/roles` | 无 | 获取角色库（已上架） |
|
||
| GET | `/api/roles/:id` | 无 | 获取角色详情 |
|
||
| GET | `/api/roles/my/roles` | JWT | 获取我创建的角色 |
|
||
| POST | `/api/roles` | JWT | 发布新角色 |
|
||
| PUT | `/api/roles/:id` | JWT | 编辑角色 |
|
||
| GET | `/api/roles/:id/full` | JWT | 获取角色完整信息（含 SOUL.md） |
|
||
|
||
### API Key 管理
|
||
|
||
| 方法 | 路径 | 认证 | 说明 |
|
||
|------|------|------|------|
|
||
| POST | `/api/apikeys` | JWT | 生成 API Key（明文仅返回一次） |
|
||
| GET | `/api/apikeys` | JWT | 列出所有 API Key（脱敏） |
|
||
| DELETE | `/api/apikeys/:id` | JWT | 删除 API Key |
|
||
|
||
### Hermes 配置拉取
|
||
|
||
| 方法 | 路径 | 认证 | 说明 |
|
||
|------|------|------|------|
|
||
| GET | `/api/hermes/roles/:id/SOUL.md` | API Key / JWT | 拉取 SOUL.md（text/plain） |
|
||
| GET | `/api/hermes/roles/:id/config.yaml` | API Key / JWT | 拉取 config.yaml（text/plain） |
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 运行全部 E2E 测试（35 个用例）
|
||
npm test
|
||
|
||
# 查看测试报告
|
||
npx playwright show-report
|
||
```
|
||
|
||
测试覆盖：认证流程、角色发布/编辑、角色库浏览、导航与可访问性。
|
||
|
||
## 安全
|
||
|
||
- **JWT 密钥**：生产环境必须设置 `JWT_SECRET` 环境变量，未设置时 fail-fast 抛错
|
||
- **密码存储**：bcrypt 哈希（10 轮盐），不存明文
|
||
- **API Key 存储**：SHA-256 哈希存储，明文仅显示一次
|
||
- **XSS 防护**：所有用户可控数据通过 `escapeHtml()` 转义后插入 DOM
|
||
- **YAML 注入防护**：config.yaml 生成时对用户可控字段做双引号转义和换行符过滤
|
||
- **所有权校验**：所有角色操作验证 `creatorId === req.userId`
|
||
- **.env 文件权限**：部署脚本自动设置 `chmod 600`
|
||
|
||
## License
|
||
|
||
MIT
|