# 哆啦A梦百宝箱 — 部署文档 ## 架构概览 ``` ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │ 浏览器 │────▶│ Nginx │────▶│ Go 后端 │────▶ MySQL │ (Vue SPA) │ │ (反向代理) │ │ :8080 │────▶ Redis └──────────────┘ └──────────────┘ │ │────▶ Python │ OCR 子进程│ 开发模式: └──────────┘ 前端 :3000 ──(Vite Proxy)──▶ 后端 :8080 ``` | 组件 | 技术栈 | 端口 | |------|--------|------| | 前端 SPA | Vue 3 + Element Plus + Vite | 3000(开发) / 80(生产) | | 后端 API | Go + Gin + GORM | 8080 | | 数据库 | MySQL 8.0+ | 3306 | | 缓存 | Redis 6+ (可选) | 6379 | | OCR | Python 3 + rapidocr-onnxruntime | 子进程调用 | --- ## 前置要求 | 依赖 | 版本 | 说明 | |------|------|------| | Go | >= 1.21 | 编译后端 | | Node.js | >= 18 | 构建前端 | | MySQL | >= 8.0 | 主数据库 | | Redis | >= 6 (可选) | 缓存，不可用时自动降级 | | Python | >= 3.9 (可选) | OCR 识别 (仅 ai-ocr 工具需要) | --- ## 快速部署 (Windows) ### 1. 数据库准备 ```sql CREATE DATABASE IF NOT EXISTS tools_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ``` 首次启动后端会自动创建表并导入种子数据（6 分类、110 工具、8 条 AI 提示词、2 个默认用户）。 ### 2. 后端部署 ```bash # 编译 cd backend go build -o tools-server.exe . # 修改配置 (config.yaml) # 修改 database.password, jwt.secret 等生产环境参数 # 启动 tools-server.exe # 服务运行在 http://0.0.0.0:8080 ``` ### 3. 前端部署 ```bash cd frontend # 安装依赖 npm install # 修改 Vite 代理配置 (vite.config.js) — 开发用 # 生产环境不需要 proxy，由 Nginx 处理 # 构建 npm run build # 输出在 dist/ 目录，部署到 Nginx 的 html 目录即可 ``` ### 4. OCR 配置 (可选) ```bash pip install rapidocr-onnxruntime # 验证: python -c "from rapidocr_onnxruntime import RapidOCR; print('ok')" ``` --- ## 生产部署方案 ### 方案 A: Nginx 反向代理 (推荐) ``` 用户 ──▶ Nginx (:80) ──▶ /api/* ──▶ Go 后端 (:8080) ──▶ /uploads/* ──▶ Go 后端 (:8080) ──▶ /* ──▶ 前端静态文件 (dist/) ``` **Nginx 配置:** ```nginx server { listen 80; server_name your-domain.com; root C:/path/to/frontend/dist; index index.html; # API 代理 location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_read_timeout 120s; } # 上传文件 location /uploads/ { proxy_pass http://127.0.0.1:8080; } # SPA 路由 fallback location / { try_files $uri $uri/ /index.html; } } ``` ### 方案 B: 前后端统一端口 (Go 内置静态文件) 修改 `main.go`，添加： ```go r.Static("/assets", "./frontend/dist/assets") r.StaticFile("/", "./frontend/dist/index.html") r.NoRoute(func(c *gin.Context) { c.File("./frontend/dist/index.html") }) ``` 编译后单文件部署，无需 Nginx。 ### 方案 C: Docker Compose ```yaml version: '3.8' services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: ${DB_PASSWORD} MYSQL_DATABASE: tools_db volumes: - mysql_data:/var/lib/mysql restart: always redis: image: redis:7-alpine restart: always backend: build: ./backend depends_on: [mysql, redis] environment: - DB_PASSWORD=${DB_PASSWORD} - JWT_SECRET=${JWT_SECRET} restart: always frontend: image: nginx:alpine volumes: - ./frontend/dist:/usr/share/nginx/html - ./nginx.conf:/etc/nginx/conf.d/default.conf ports: - "80:80" depends_on: [backend] ``` --- ## 配置说明 ### config.yaml ```yaml server: port: 8080 mode: debug # 生产环境改为 release database: host: 127.0.0.1 port: 3306 user: root password: root # 生产环境务必修改！ name: tools_db redis: host: 127.0.0.1 port: 6379 password: "" db: 0 jwt: secret: tools-jwt-secret-2024 # 生产环境务必修改！ expire: 168 # Token 过期时间（小时） log: level: info file: logs/app.log ``` --- ## API 总览 共 **33 个 API 端点**，全部以 `/api` 为前缀。 ### 公开接口 | 方法 | 路径 | 说明 | |------|------|------| | POST | `/api/auth/register` | 用户注册 | | POST | `/api/auth/login` | 用户登录 | | POST | `/api/auth/admin/login` | 管理员登录 | | GET | `/api/public/categories` | 获取分类列表 | | GET | `/api/public/tools` | 获取工具列表 (?category_id=&hot=&search=) | | GET | `/api/public/tools/:id` | 获取工具详情 | | POST | `/api/feedback` | 提交反馈 | | GET | `/api/ai/config` | 获取 AI 配置（不含 Key） | | GET | `/api/ai/ocr/check` | 检测 OCR 可用性 | | GET | `/api/ai/prompts` | 获取所有 AI 提示词 | | GET | `/api/ai/prompts/:tool_key` | 获取单个 AI 提示词 | ### 需要认证 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/user/profile` | 获取用户信息 | | POST | `/api/tools/:id/use` | 记录工具使用 | | POST | `/api/ai/proxy` | AI 对话代理 | | POST | `/api/ai/ocr` | OCR 识别 | ### 管理员接口 (需 admin 角色) | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/admin/dashboard` | 仪表盘统计 | | GET/POST | `/api/admin/tools` | 工具列表/创建 | | PUT/DEL | `/api/admin/tools/:id` | 工具编辑/删除 | | GET/POST | `/api/admin/categories` | 分类列表/创建 | | PUT/DEL | `/api/admin/categories/:id` | 分类编辑/删除 | | GET | `/api/admin/users` | 用户列表 | | PUT | `/api/admin/users/:id` | 用户编辑 | | GET | `/api/admin/feedback` | 反馈列表 | | GET | `/api/admin/feedback/:id` | 反馈详情 | | PUT | `/api/admin/feedback/:id` | 回复/处理反馈 | | GET/PUT | `/api/admin/ai/config` | AI 配置管理 | | GET/PUT | `/api/admin/ai/prompts` | AI 提示词管理 | --- ## 安全清单 部署到生产环境前请逐一检查： - [ ] 修改 `config.yaml` 中 `database.password`（不要使用 root/root） - [ ] 修改 `config.yaml` 中 `jwt.secret` 为随机字符串 - [ ] 修改 `config.yaml` 中 `server.mode` 为 `release` - [ ] 在 Nginx 层配置 HTTPS (Let's Encrypt / 域名证书) - [ ] 限制 Nginx 中的 `Access-Control-Allow-Origin` 为具体域名 - [ ] 修改默认管理员密码 (admin/admin123) - [ ] 配置合理的 `proxy_read_timeout`（AI 接口可能需要 120s+） - [ ] 定期备份 MySQL 数据库 - [ ] 检查上传目录 `uploads/feedback/` 的写入权限 - [ ] 如果不需要 OCR，可以不安装 Python（系统自动降级为 Tesseract.js 前端识别） --- ## 默认账号 | 角色 | 用户名 | 密码 | |------|--------|------| | 管理员 | admin | admin123 | | 普通用户 | user | user123 | --- ## 运维命令 ```bash # 后端 cd backend go build -o tools-server.exe . # 编译 tools-server.exe # 启动 # Ctrl+C 停止 # 前端 cd frontend npm install # 安装依赖 npm run dev # 开发模式 :3000 npm run build # 生产构建 → dist/ npm run preview # 预览构建结果 ``` ## 常见问题 **Q: Redis 连接失败怎么办？** 系统自动降级，缓存功能不可用但所有业务功能正常。 **Q: OCR 不可用怎么办？** AI 开启时自动检查 AI 视觉模型是否可用；关闭时使用 Tesseract.js（浏览器端）。 **Q: AI 工具提示词为空？** 进入管理后台 → AI 提示词管理，检查是否有种子数据。首次启动后自动填充 8 条系统提示词。 **Q: 前端页面刷新后 404？** 这是 SPA 的常见问题。确保 Nginx 配置了 `try_files $uri $uri/ /index.html;`。