194 lines
6.2 KiB
Markdown
194 lines
6.2 KiB
Markdown
项目概览
|
||
|
||
- 技术栈：Go、Gin、阿里云 OSS
|
||
- 功能：登录验签（JWT）、文件上传到 OSS（需要登录）、新增用户注册（需验证码，默认启用）
|
||
- 结构：`main.go` + `internal/*` 模块化配置、认证、中间件、OSS 封装与接口处理
|
||
|
||
环境变量
|
||
|
||
- `PORT`：服务端口，默认 `8080`
|
||
- `GIN_MODE`：Gin 运行模式，建议 `release`
|
||
- `JWT_SECRET`：JWT 签名密钥
|
||
- `ADMIN_USERNAME` / `ADMIN_PASSWORD`：登录账号密码（管理员回退）
|
||
- `ALLOW_REGISTRATION`：是否允许注册，默认 `true`（可设为 `false`/`off` 关闭）
|
||
- `OSS_ENDPOINT`：OSS Endpoint（例如 `oss-cn-hangzhou.aliyuncs.com`）
|
||
- `OSS_ACCESS_KEY_ID` / `OSS_ACCESS_KEY_SECRET`：OSS 访问密钥
|
||
- `OSS_BUCKET`：目标存储桶名称
|
||
- `DB_DSN`：MySQL 连接串（不配置则使用本地默认 `root:password@tcp(127.0.0.1:3306)/go_dy?parseTime=true&charset=utf8mb4&loc=Local`）
|
||
|
||
API 设计（统一返回结构：`{"code":<int>,"message":"<string>","data":<object|null>}`）
|
||
|
||
- `GET /api/captcha/new`
|
||
|
||
- 生成验证码，返回：`{"code":0,"message":"ok","data":{"id":"<id>","image":"data:image/png;base64,<...>"}}`
|
||
- 前端展示 `image`，注册时提交 `id` 与用户输入的 `code`。
|
||
|
||
- `POST /api/register`（验证码可通过开关控制；`ALLOW_REGISTRATION` 控制是否允许注册）
|
||
- 请求（`application/x-www-form-urlencoded`）：
|
||
- 基本必填：`name`、`password`、`confirm_password`
|
||
- 当 `REGISTER_REQUIRE_CAPTCHA=true` 时额外必填：`captcha_id`、`captcha_code`
|
||
- 返回：成功写入 `users` 表（密码使用 BCrypt 哈希），失败返回具体错误（缺失字段、验证码错误、用户已存在等）。
|
||
|
||
- `POST /api/login`
|
||
|
||
- 请求（`application/x-www-form-urlencoded`）：`name=<用户名>&password=<密码>`
|
||
- 认证顺序：
|
||
1. 若启用注册且数据库可用，优先使用数据库用户验证（BCrypt）。
|
||
2. 未命中或数据库不可用时，回退到管理员账号验证（`ADMIN_USERNAME`/`ADMIN_PASSWORD`）。
|
||
|
||
- `POST /api/upload`（需 `Authorization: Bearer <JWT>`）
|
||
- 鉴权：仅从请求头 `Authorization: Bearer <JWT>` 读取 token。
|
||
- `multipart/form-data`，字段：`file`（必填）、`prefix`（可选）
|
||
- 成功：返回对象 `key` 与公开 URL。
|
||
|
||
快速本地运行
|
||
|
||
1. 安装 Go（1.20+）
|
||
2. 可选：在项目根目录创建 `.env`（参考 `.env.example`），系统会在启动时自动加载。
|
||
3. 依赖整理与启动：
|
||
|
||
```
|
||
go mod tidy
|
||
go run .
|
||
```
|
||
|
||
生产部署（Alibaba Cloud Linux 3.2104 LTS）
|
||
|
||
1. 在服务器上安装 Go（或在本机交叉编译后上传）：
|
||
|
||
```
|
||
# 在服务器上
|
||
sudo dnf install -y golang
|
||
# 或本地交叉编译
|
||
GOOS=linux GOARCH=amd64 go build -o go-dy
|
||
scp go-dy user@server:/opt/go-dy/go-dy
|
||
```
|
||
|
||
2. 配置环境文件 `/etc/go-dy.env`：
|
||
|
||
```
|
||
PORT=18080
|
||
GIN_MODE=release
|
||
JWT_SECRET=your-secure-secret
|
||
ADMIN_USERNAME=admin
|
||
ADMIN_PASSWORD=strong-password
|
||
ALLOW_REGISTRATION=true
|
||
OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
|
||
OSS_ACCESS_KEY_ID=AKID...
|
||
OSS_ACCESS_KEY_SECRET=AKSECRET...
|
||
OSS_BUCKET=your-bucket
|
||
DB_DSN="root:password@tcp(127.0.0.1:3306)/go_dy?parseTime=true&charset=utf8mb4&loc=Local"
|
||
```
|
||
|
||
3. 创建 Systemd 服务 `/etc/systemd/system/go-dy.service`（略，同前）。
|
||
|
||
接口调用示例
|
||
|
||
- 获取验证码：
|
||
|
||
```
|
||
curl -s http://localhost:8080/api/captcha/new | jq
|
||
# 返回 data.id 与 data.image（base64 PNG），前端展示图片并保存 id
|
||
```
|
||
|
||
- 注册用户（带验证码与确认密码）：
|
||
|
||
```
|
||
curl -s -X POST http://localhost:8080/api/register \
|
||
-H 'Content-Type: application/x-www-form-urlencoded' \
|
||
-d 'name=alice&password=secret&confirm_password=secret&captcha_id=<ID>&captcha_code=<CODE>'
|
||
```
|
||
|
||
- 登录获取令牌（优先数据库用户，其次管理员）：
|
||
|
||
```
|
||
curl -s -X POST http://localhost:8080/api/login \
|
||
-H 'Content-Type: application/x-www-form-urlencoded' \
|
||
-d 'name=alice&password=secret'
|
||
```
|
||
|
||
- 携带令牌上传文件：
|
||
|
||
```
|
||
curl -s -X POST http://localhost:8080/api/upload \
|
||
-H 'Authorization: Bearer <TOKEN>' \
|
||
-F 'file=@/path/to/file.png' \
|
||
-F 'prefix=uploads/images'
|
||
```
|
||
|
||
注意事项
|
||
|
||
- 注册默认开启，可通过 `ALLOW_REGISTRATION=false` 关闭。
|
||
- 验证码使用内存存储，自动过期（默认约 10 分钟）；过期需重新获取。
|
||
- 若未配置 `DB_DSN`，系统会尝试使用本地默认 MySQL；生产环境请设置强密码并限制访问。
|
||
- `JWT_SECRET` 请务必设置为强随机值。
|
||
- 遇到 OSS 403/签名错误，检查 AK/SK、Endpoint、Bucket 名称与权限策略。
|
||
|
||
项目结构
|
||
|
||
```
|
||
.
|
||
├── main.go
|
||
├── internal
|
||
│ ├── auth
|
||
│ │ └── jwt.go
|
||
│ ├── config
|
||
│ │ └── config.go
|
||
│ ├── handlers
|
||
│ │ ├── login.go
|
||
│ │ └── upload.go
|
||
│ ├── middleware
|
||
│ │ └── auth.go
|
||
│ └── oss
|
||
│ └── oss.go
|
||
└── README.md
|
||
```
|
||
|
||
# go-dy
|
||
|
||
## 接口说明
|
||
|
||
### 1. 获取验证码
|
||
|
||
- `GET /api/captcha/new`
|
||
- 返回：`{ id: string, image_base64: string }`
|
||
|
||
### 2. 注册
|
||
|
||
- `POST /api/register`
|
||
- Form 字段：
|
||
- 基本必填：`name`, `password`, `confirm_password`
|
||
- 当 `REGISTER_REQUIRE_CAPTCHA=true` 时额外必填：`captcha_id`, `captcha_code`
|
||
- 返回：`{ code: 0, message: "ok" }`
|
||
|
||
### 3. 登录（仅使用数据库校验）
|
||
|
||
- `POST /api/login`
|
||
- Form 字段：
|
||
- `name`, `password`
|
||
- `captcha_id`, `captcha_code`（当 `LOGIN_REQUIRE_CAPTCHA=true` 时必填；默认你已设置为 `false`）
|
||
- 返回：`{ token: string }`
|
||
|
||
说明：
|
||
|
||
- 登录仅校验数据库 `users` 表，不再使用管理员账号回退。
|
||
- 若数据库不可用，接口将返回 `503 Service Unavailable`。
|
||
- 登录和注册均使用同一验证码生成接口。`image_base64` 为 `data:image/png;base64,...`，前端可直接展示。
|
||
- 若需要关闭登录验证码，可在 `.env` 或环境变量中设置：`LOGIN_REQUIRE_CAPTCHA=false`。
|
||
|
||
### 4. 健康检查
|
||
|
||
- `GET /api/health`
|
||
- 返回：`{ code, message, status, db, error? }`
|
||
|
||
## 环境变量
|
||
|
||
- `PORT`（默认 `8080`）
|
||
- `JWT_SECRET`
|
||
- `ADMIN_USERNAME`, `ADMIN_PASSWORD`
|
||
- `DB_DSN`
|
||
- `ALLOW_REGISTRATION`（默认 `true`）
|
||
- `LOGIN_REQUIRE_CAPTCHA`（默认 `true`）
|
||
- `REGISTER_REQUIRE_CAPTCHA`（默认 `true`）
|
||
- `OSS_ENDPOINT`, `OSS_ACCESS_KEY_ID`, `OSS_ACCESS_KEY_SECRET`, `OSS_BUCKET`
|