commit 095e2869cbf55da9e50bc3d6ea1f351c746d97a7
Author: linzhongyan <1577714120@qq.com>
Date:   Tue Oct 28 16:58:35 2025 +0800

    first commit

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..eff68e7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,193 @@
+项目概览
+
+- 技术栈：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`