113 lines
3.9 KiB
Markdown
113 lines
3.9 KiB
Markdown
# 哈尔滨美食地图（0451meishiditu）管理后台 & 后端
|
||
|
||
## 技术栈
|
||
|
||
- 后端：Go + Gin + GORM + MySQL + Redis
|
||
- 管理后台：Vue3 + Vite + TypeScript + Element Plus + ECharts
|
||
- 部署：Docker Compose + Nginx
|
||
|
||
## 快速启动（Docker Compose）
|
||
|
||
1. 复制环境变量文件
|
||
- `backend/.env.example` → `backend/.env`
|
||
- `admin/.env.example` → `admin/.env`
|
||
|
||
2. 启动（会同时启动 MySQL、Redis、后端、管理后台、Swagger UI）
|
||
- `docker compose -f deploy/docker-compose.full.yml up -d --build`
|
||
|
||
3. 访问
|
||
- 管理后台：`http://localhost:5173`
|
||
- 后端健康检查：`http://localhost:8080/healthz`
|
||
- Swagger 文档：`http://localhost:8081`（加载 `docs/openapi.yaml`）
|
||
|
||
## 已实现模块（管理后台）
|
||
|
||
- 数据概览（Dashboard）
|
||
- 店铺管理（列表/详情/上下架/删除）
|
||
- 分类管理
|
||
- 评论管理（审核/删除）
|
||
- 商家入驻审核（通过/拒绝）
|
||
- 排行管理（查看/重算综合分）
|
||
- 用户管理（列表/详情/启用禁用）
|
||
- 管理员管理（新增/重置密码/启用禁用）
|
||
- APIKey 管理（创建/撤销/查看使用时间）
|
||
- 系统设置（CORS）
|
||
|
||
## 认证与安全（非常重要）
|
||
|
||
1) APIKey（所有 `/api/**` 必须携带）
|
||
- Header：`X-API-Key: <apikey>`
|
||
- 开发环境默认值来自 `backend/.env`：`API_KEY=dev-api-key-change-me`
|
||
|
||
2) 管理端 JWT（管理端 `/api/admin/**`，除登录外必须携带）
|
||
- Header：`Authorization: Bearer <admin_token>`
|
||
|
||
3) 用户端 JWT（用户端需要登录的接口必须携带）
|
||
- Header：`Authorization: Bearer <user_token>`
|
||
|
||
## 默认管理员账号（首次启动初始化）
|
||
|
||
由 `backend/.env` 控制（首次启动会自动创建）：
|
||
- `ADMIN_INIT_USERNAME=admin`
|
||
- `ADMIN_INIT_PASSWORD=admin123456`
|
||
|
||
建议：
|
||
- 生产环境务必修改 `JWT_SECRET`、`API_KEY`（或使用 `API_KEY_HASH`）
|
||
- 首次进入后台后，在「管理员管理」创建新管理员，并禁用默认管理员
|
||
|
||
## CORS 跨域设置（支持手动配置）
|
||
|
||
默认允许：
|
||
- `http://localhost:5173`
|
||
|
||
配置方式：
|
||
1) 推荐：在管理后台「系统设置」配置
|
||
- 一行一个 Origin，例如：
|
||
- `http://localhost:5173`
|
||
- `https://admin.example.com`
|
||
- 支持 `*`（仅建议开发环境）
|
||
- 保存后立即生效（内存热更新 + 持久化到 DB）
|
||
|
||
2) 通过 `backend/.env` 配置
|
||
- `CORS_ALLOW_ORIGINS`：使用英文逗号分隔
|
||
- 示例：`CORS_ALLOW_ORIGINS=http://localhost:5173,https://admin.example.com`
|
||
|
||
## 用户注册/登录验证码
|
||
|
||
- `GET /api/captcha/new` 获取验证码（返回 `captcha_id` + `svg`）
|
||
- `POST /api/user/register`、`POST /api/user/login` 需要携带：
|
||
- `captcha_id`
|
||
- `captcha_code`
|
||
|
||
## 管理员登录验证码
|
||
|
||
- `POST /api/admin/login` 同样需要携带 `captcha_id` + `captcha_code`（防止暴力破解）
|
||
- 管理后台登录页已集成验证码展示与点击刷新
|
||
|
||
## 公共读取接口（前端可调用）
|
||
|
||
这些接口仍然需要 `X-API-Key`，但不需要管理员 JWT：
|
||
- 分类列表：`GET /api/categories`（只返回 enabled=true）
|
||
- 店铺列表：`GET /api/stores`（只返回 active）
|
||
- 店铺详情：`GET /api/stores/:id`（只返回 active）
|
||
- 店铺评论：`GET /api/stores/:id/reviews`（只返回 approved）
|
||
- 店铺排行：`GET /api/rankings/stores`
|
||
|
||
详见：`docs/API.md`（中文说明）和 `docs/openapi.yaml`（Swagger）
|
||
|
||
## 图片上传与目录权限
|
||
|
||
- 上传接口：`POST /api/admin/upload`（`multipart/form-data`，字段名 `file`）
|
||
- Docker 下默认把上传目录挂载到数据卷：`backend_uploads:/app/static/upload`
|
||
- 已处理常见的 `mkdir failed` 权限问题（容器启动时自动创建/授权上传目录）
|
||
|
||
## 文档
|
||
|
||
- Swagger/OpenAPI：`docs/openapi.yaml`（Swagger UI：`http://localhost:8081`）
|
||
- 中文接口说明：`docs/API.md`
|
||
|
||
## 常见启动问题
|
||
|
||
- 容器名/端口/数据卷冲突：执行 `docker compose -f deploy/docker-compose.full.yml down -v` 后再 `up -d --build`
|
||
- 注意：`down -v` 会清空 MySQL/Redis 数据
|