# admin_frontend 启动指南

## 📋 前置要求

- Node.js (推荐 v16 或更高版本)
- npm 或 yarn
- 后端服务已启动 (backend)

## 🚀 开发环境启动

### 方法 1: 使用 npm（推荐）

```bash
# 1. 进入项目目录
cd admin_frontend

# 2. 安装依赖（首次运行或依赖更新时）
npm install

# 3. 启动开发服务器
npm run dev
```

### 方法 2: 使用 yarn

```bash
cd admin_frontend
yarn install
yarn dev
```

### 启动成功标志

看到类似以下输出表示启动成功：

```
VITE v8.0.4  ready in 500 ms

➜  Local:   http://localhost:5174/
➜  Network: http://140.3.181.9:5174/
➜  press h + enter to show help
```

### 访问地址

- **本机访问**: http://localhost:5174/
- **局域网访问**: http://你的IP:5174/

**注意**: admin_frontend 使用端口 **5174**（与 user_frontend 的 5173 不同）

## 🏭 生产环境部署

### 步骤 1: 配置生产环境变量

编辑 `.env.production` 文件：

```env
# 后端 API 基础地址（生产环境）
VITE_API_BASE_URL=https://api.yourdomain.com/api

# 后端主机地址（用于流式请求等特殊场景）
VITE_API_HOST=https://api.yourdomain.com
```

**注意**: 
- 生产环境使用 `https://`（安全协议）
- 替换为你的实际域名

### 步骤 2: 构建生产版本

```bash
# 进入项目目录
cd admin_frontend

# 构建生产版本
npm run build
```

构建完成后，会在 `dist` 目录生成静态文件。

### 步骤 3: 预览生产构建（可选）

```bash
# 本地预览生产构建
npm run preview
```

访问 http://localhost:4173/ 查看生产版本。

### 步骤 4: 部署到服务器

#### 方案 A: 使用 Nginx

1. **上传构建文件**
   ```bash
   # 将 dist 目录上传到服务器
   scp -r dist/* user@server:/var/www/admin_frontend/
   ```

2. **配置 Nginx**
   
   创建 `/etc/nginx/sites-available/admin_frontend`:
   ```nginx
   server {
       listen 80;
       server_name admin.yourdomain.com;
       
       root /var/www/admin_frontend;
       index index.html;
       
       location / {
           try_files $uri $uri/ /index.html;
       }
       
       # API 代理（可选）
       location /api {
           proxy_pass http://localhost:8000;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           proxy_set_header Host $host;
           proxy_cache_bypass $http_upgrade;
       }
   }
   ```

3. **启用站点**
   ```bash
   sudo ln -s /etc/nginx/sites-available/admin_frontend /etc/nginx/sites-enabled/
   sudo nginx -t
   sudo systemctl reload nginx
   ```

#### 方案 B: 使用 Apache

1. **上传构建文件**
   ```bash
   scp -r dist/* user@server:/var/www/html/admin_frontend/
   ```

2. **配置 .htaccess**
   
   在 `/var/www/html/admin_frontend/` 创建 `.htaccess`:
   ```apache
   <IfModule mod_rewrite.c>
     RewriteEngine On
     RewriteBase /
     RewriteRule ^index\.html$ - [L]
     RewriteCond %{REQUEST_FILENAME} !-f
     RewriteCond %{REQUEST_FILENAME} !-d
     RewriteRule . /index.html [L]
   </IfModule>
   ```

#### 方案 C: 使用静态托管服务

**Vercel**:
```bash
npm install -g vercel
vercel --prod
```

**Netlify**:
```bash
npm install -g netlify-cli
netlify deploy --prod --dir=dist
```

## 🔧 环境配置

### 开发环境 (.env.development)

```env
# 本地开发
VITE_API_BASE_URL=http://localhost:8000/api
VITE_API_HOST=http://localhost:8000

# 或使用 IP 地址
VITE_API_BASE_URL=http://140.3.181.9:8000/api
VITE_API_HOST=http://140.3.181.9:8000
```

### 生产环境 (.env.production)

```env
# 生产环境（使用域名和 HTTPS）
VITE_API_BASE_URL=https://api.yourdomain.com/api
VITE_API_HOST=https://api.yourdomain.com
```

## 📝 可用命令

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

# 代码检查
npm run lint
```

## 🔑 管理员账号

### 创建管理员账号

在后端目录运行：

```bash
cd backend
python create_admin.py
```

按提示输入管理员信息。

### 默认管理员账号（如果已创建）

- 用户名: admin
- 密码: （创建时设置的密码）

## 🐛 常见问题

### 1. 端口被占用

**错误信息**:
```
Port 5174 is in use
```

**解决方案**:
```bash
# 查找占用端口的进程
netstat -ano | findstr "5174"

# 结束进程（替换 PID）
taskkill /PID <进程ID> /F

# 或修改端口
# 编辑 vite.config.js，修改 port 配置
```

### 2. 依赖安装失败

**解决方案**:
```bash
# 清除缓存
npm cache clean --force

# 删除 node_modules 和 package-lock.json
rm -rf node_modules package-lock.json

# 重新安装
npm install
```

### 3. 构建失败

**解决方案**:
```bash
# 检查 Node.js 版本
node --version

# 更新依赖
npm update

# 清除构建缓存
rm -rf dist
npm run build
```

### 4. 环境变量不生效

**解决方案**:
- 确保环境变量以 `VITE_` 开头
- 修改 `.env` 文件后重启开发服务器
- 清除浏览器缓存 (Ctrl+Shift+Delete)

### 5. API 请求失败

**检查清单**:
- [ ] 后端服务是否启动
- [ ] 环境变量配置是否正确
- [ ] 后端 CORS 是否配置
- [ ] 网络连接是否正常

### 6. 流式请求失败（AI 生成工具、敏感词分析）

**检查清单**:
- [ ] `VITE_API_HOST` 配置是否正确
- [ ] 后端流式接口是否正常
- [ ] 浏览器是否支持 Fetch API
- [ ] 网络连接是否稳定

## 🔍 调试技巧

### 查看环境变量

在浏览器控制台（F12）运行：
```javascript
console.log('API URL:', import.meta.env.VITE_API_BASE_URL);
console.log('API Host:', import.meta.env.VITE_API_HOST);
console.log('Mode:', import.meta.env.MODE);
```

### 查看网络请求

1. 打开开发者工具（F12）
2. 切换到 Network 标签
3. 刷新页面
4. 查看请求的 URL 和状态

### 查看控制台错误

1. 打开开发者工具（F12）
2. 切换到 Console 标签
3. 查看错误信息

## 📊 性能优化

### 开发环境

```javascript
// vite.config.js
export default defineConfig({
  server: {
    hmr: true, // 热更新
    open: false, // 不自动打开浏览器
  },
});
```

### 生产环境

```javascript
// vite.config.js
export default defineConfig({
  build: {
    minify: 'terser', // 代码压缩
    sourcemap: false, // 不生成 sourcemap
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          antd: ['antd'],
        },
      },
    },
  },
});
```

## 🔒 安全建议

### 开发环境
- ✅ 使用 HTTP
- ✅ 可以使用 IP 地址
- ✅ 允许所有来源（CORS）

### 生产环境
- ✅ 使用 HTTPS
- ✅ 使用域名而非 IP
- ✅ 严格配置 CORS
- ✅ 启用防火墙和安全组
- ✅ 定期更新依赖
- ✅ 不要暴露敏感信息
- ✅ 使用强密码策略
- ✅ 启用访问日志

## 🎯 管理后台功能

- 用户管理
- 数字员工管理
- 工具管理（AI 生成工具）
- 模型管理
- 对话消息管理
- 数据分析中心

## 📚 相关文档

- `package.json` - 项目配置和依赖
- `vite.config.js` - Vite 配置
- `.env.development` - 开发环境变量
- `.env.production` - 生产环境变量
- `ENV_CONFIG_GUIDE.md` - 环境变量配置指南
- `FEATURES.md` - 功能说明

## ✅ 启动检查清单

### 开发环境
- [ ] Node.js 已安装
- [ ] 依赖已安装 (npm install)
- [ ] 后端服务已启动
- [ ] 管理员账号已创建
- [ ] 环境变量已配置
- [ ] 开发服务器已启动
- [ ] 浏览器可以访问

### 生产环境
- [ ] 生产环境变量已配置
- [ ] 构建成功 (npm run build)
- [ ] 静态文件已生成 (dist 目录)
- [ ] Web 服务器已配置
- [ ] 域名已解析
- [ ] HTTPS 已配置
- [ ] 功能测试通过
- [ ] 安全措施已配置

## 🎉 快速开始

```bash
# 一键启动开发环境
cd admin_frontend && npm install && npm run dev

# 一键构建生产版本
cd admin_frontend && npm run build
```

## 🔗 相关项目

- **user_frontend** (端口 5173) - 用户前端
- **backend** (端口 8000) - 后端 API

---

**祝你管理顺利！** 🚀
