# 飞鸿geo

**Repository Path**: bidcms/feihong-geo

## Basic Information

- **Project Name**: 飞鸿geo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-01
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GEO 系统后端（Gin + GORM）

> Gin 1.10 + GORM 1.25 + 多数据库（SQLite / MySQL / PostgreSQL）
> 单一代码库，一键切换数据库

## 目录

```
go-backend/
├── cmd/server/main.go                # 启动入口
├── internal/
│   ├── api/
│   │   ├── middleware/               # 中间件
│   │   │   ├── cors.go
│   │   │   ├── trace.go
│   │   │   ├── logger.go
│   │   │   ├── jwt.go                # 鉴权 + 角色门控
│   │   │   ├── ratelimit.go          # 令牌桶限流
│   │   │   └── city_scope.go         # 城市数据隔离
│   │   └── v1/
│   │       └── router.go             # 全部路由
│   ├── config/config.go              # 配置加载
│   ├── controller/                   # 控制器层（按业务）
│   │   ├── auth_controller.go
│   │   ├── city_controller.go
│   │   ├── shop_controller.go
│   │   ├── keyword_controller.go
│   │   ├── article_controller.go
│   │   ├── schema_controller.go
│   │   ├── stats_controller.go
│   │   └── system_controller.go
│   ├── database/                     # 多数据库驱动
│   │   ├── driver.go
│   │   ├── factory.go
│   │   ├── sqlite.go
│   │   ├── mysql.go
│   │   ├── postgres.go
│   │   ├── migrate.go
│   │   ├── seed.go
│   │   └── global.go
│   ├── model/
│   │   ├── entity/                   # 数据库实体
│   │   ├── dto/                      # 入参
│   │   ├── vo/                       # 出参
│   │   └── common/response.go        # ApiResponse
│   ├── service/                      # 业务层
│   │   ├── city_service.go
│   │   ├── shop_service.go
│   │   ├── keyword_service.go
│   │   ├── article_service.go
│   │   ├── schema_service.go
│   │   ├── stats_service.go
│   │   ├── user_service.go
│   │   ├── oplog_service.go
│   │   └── bannedword_service.go
│   └── utils/                        # 工具
│       ├── jwt.go
│       ├── password.go
│       ├── logger.go
│       ├── response.go
│       ├── validator.go
│       └── json.go
├── configs/config.yaml              # 配置文件(可选)
├── Dockerfile
├── docker-compose.yml
├── Makefile
├── go.mod
└── README.md
```

## 中间件清单

| 中间件 | 作用 | 顺序 |
| --- | --- | --- |
| `Recover` | panic 恢复 + zap 记录 | 1 |
| `Logger` | HTTP 访问日志（zap） | 2 |
| `Cors` | CORS 跨域（白名单） | 3 |
| `TraceID` | 注入/透传 Trace ID | 4 |
| `JWT` | Bearer Token 鉴权 | 业务 |
| `RoleAdmin` | 仅超管 | 业务 |
| `RoleOperator` | 操作员以上 | 业务 |
| `CityScope` | 城市数据隔离 | 业务 |
| `RateLimiter` | IP 令牌桶限流 | 全局 |

## 路由结构

```
/healthz                                              公开
/api/v1/auth/login                                    公开
/api/v1/auth/{logout,profile,password}                JWT
/api/v1/cities                                        JWT
/api/v1/cities/{POST,PUT:id,DELETE:id}                JWT + RoleAdmin
/api/v1/shops                                         JWT
/api/v1/shops/{:id,by-city,import,export}             JWT
/api/v1/keywords                                      JWT
/api/v1/keywords/{:id,import,blank}                   JWT
/api/v1/articles                                      JWT
/api/v1/articles/{:id,generate,batch-generate,task,export}  JWT
/api/v1/articles/templates[/:id]                       JWT
/api/v1/schema/{local-business/:shop_id,faq,article/:article_id}  JWT
/api/v1/stats/{coverage,ai-cite,blank,competitor,record}  JWT
/api/v1/system/users[/:id]                            JWT + RoleAdmin
/api/v1/system/{logs,banned-words[/:id]}               JWT
```

## 启动

### 方式 1：Makefile（推荐）

```bash
make tidy          # 整理依赖
make sqlite        # SQLite 模式启动
make mysql         # MySQL 模式
make postgres      # PostgreSQL 模式
```

### 方式 2：直接 go run

```bash
go mod tidy
DB_DRIVER=sqlite DB_FILE=./data/geo.db go run cmd/server/main.go
```

### 方式 3：Docker

```bash
docker-compose up -d
# 健康检查：curl http://localhost:8080/healthz
```

## 配置文件

`configs/config.yaml` 为可选项，**优先级低于环境变量**：

```
环境变量 > configs/config.yaml > 代码内默认值
```

可被环境变量全部覆盖；如果需要多套环境（如本地/预发/生产），复制为 `config.local.yaml` 后通过 `CONFIG_PATH` 指定：

```bash
CONFIG_PATH=./configs/config.local.yaml go run cmd/server/main.go
```

文件加载失败（不存在或解析错误）时仅打印提示并继续运行，不会中断启动。

## 环境变量

| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `PORT` | 8080 | HTTP 端口 |
| `GIN_MODE` | debug | debug/release/test |
| `DB_DRIVER` | sqlite | sqlite/mysql/postgres |
| `DB_DSN` | - | 完整 DSN（覆盖其他字段） |
| `DB_HOST` | 127.0.0.1 | MySQL/PG 主机 |
| `DB_PORT` | 3306 | MySQL:3306 PG:5432 |
| `DB_USER` | root | 用户名 |
| `DB_PASSWORD` | - | 密码 |
| `DB_NAME` | geo | 库名 |
| `DB_FILE` | ./data/geo.db | SQLite 文件 |
| `DB_SSLMODE` | disable | PG: disable/require |
| `DB_CHARSET` | utf8mb4 | MySQL 字符集 |
| `DB_MAX_OPEN` | 50 | 连接池上限 |
| `DB_MAX_IDLE` | 10 | 空闲连接数 |
| `DB_LOG_LEVEL` | 4 | GORM 日志 1-5 |
| `JWT_SECRET` | 默认 | 生产必须改 |
| `JWT_EXPIRE` | 7200 | 秒 |
| `LLM_PROVIDER` | qwen | qwen/doubao/deepseek |
| `LLM_API_KEY` | - | API Key |
| `LLM_BASE_URL` | - | 端点 |
| `LLM_MODEL` | qwen-plus | 模型 |
| `LLM_TIMEOUT` | 30 | 超时秒 |

## 默认账号

启动自动 Seed：
- `admin` / `Admin@123`（超管，**首次登录必须改**）

## 完整代码量

| 层 | 文件数 |
| --- | --- |
| 入口 | 1 |
| 中间件 | 6 |
| 路由 | 1 |
| 控制器 | 8 |
| 数据库驱动 | 7 |
| Entity | 5 |
| DTO | 6 |
| VO | 7 |
| Service | 9 |
| Utils | 7 |
| 配置/部署 | 4 |
| **合计** | **~60** |