YMhut-box-C-/server/update/README.md

# YMhut更新站 - Go 版本

这是 Node.js 版本的完整 Go 实现，使用 Gin 框架构建，提供了更好的性能和更完善的 UI/UX 体验。

## 功能特性

- ✅ 完整复现 Node.js 版本的所有功能
- ✅ 产品列表展示（自动从 downloads 目录读取）
- ✅ JSON API 接口（tool-status.json, update-info.json, media-types.json 等）
- ✅ 文件下载功能（支持安全校验）
- ✅ 历史版本查看
- ✅ 改进的 UI/UX（增强动画、优化响应式设计）
- ✅ 完整的错误处理（404、500 页面）
- ✅ 彩色日志系统
- ✅ **后台管理系统**（新增）
  - 用户注册和登录（第一个用户自动成为管理员）
  - 密码强度验证（防止弱密码）
  - 路由管理（可视化添加、编辑、删除路由）
  - 文件管理（浏览、查看、编辑文件）
  - 配置管理（编辑 JSON 配置文件）
  - 日志查看（实时查看系统日志）
  - 系统信息（查看系统统计）

## 项目结构

```
go/
├── main.go              # 主入口文件
├── go.mod               # Go 模块依赖
├── go.sum               # 依赖校验文件
├── config/
│   └── routes.go        # 路由配置
├── models/              # 数据模型
│   ├── user.go          # 用户模型
│   └── route.go         # 路由模型
├── database/            # 数据库
│   └── db.go            # 数据库初始化
├── handlers/            # 请求处理
│   ├── auth.go          # 认证处理
│   └── admin.go         # 后台管理处理
├── middleware/          # 中间件
│   └── auth.go          # 认证中间件
├── utils/
│   ├── logger.go        # 日志工具
│   ├── route-utils.go   # 路由辅助函数
│   ├── password.go      # 密码验证
│   ├── jwt.go           # JWT Token
│   └── config.go        # 配置缓存
├── views/               # HTML 模板
│   ├── index.html
│   ├── admin.html       # 后台管理界面
│   ├── 404.html
│   └── 500.html
└── public/              # 静态资源
    ├── css/
    ├── img/
    ├── fonts/
    ├── lang/
    ├── downloads/       # 下载文件目录
    └── *.json          # JSON 配置文件
```

## 前置要求

### 必需

- **Go 1.21 或更高版本**
  - 下载地址：https://golang.org/dl/
  - 安装后验证：`go version`

### 可选（用于编译）

- **Git**（用于版本控制）
- **CGO**（SQLite 需要，Windows 可能需要安装 GCC）

## 快速开始

**新手推荐**：查看 [QUICKSTART.md](./QUICKSTART.md) 获取详细的、一步一步的安装指南。

## 完整安装步骤

### 步骤 1: 检查 Go 环境

打开终端（Windows: PowerShell 或 CMD，Linux/macOS: Terminal），运行：

```bash
go version
```

**预期输出示例：**
```
go version go1.21.0 windows/amd64
```

如果显示 "command not found" 或类似错误，请先安装 Go。

### 步骤 2: 进入项目目录

```bash
# Windows (PowerShell)
cd D:\Desktop\update\go

# Windows (CMD)
cd D:\Desktop\update\go

# Linux/macOS
cd /path/to/update/go
```

### 步骤 3: 下载依赖

```bash
go mod download
```

**预期输出：**
```
go: downloading github.com/gin-gonic/gin v1.9.1
go: downloading github.com/golang-jwt/jwt/v5 v5.2.0
go: downloading gorm.io/gorm v1.25.5
...
```

### 步骤 4: 整理依赖（生成 go.sum）

```bash
go mod tidy
```

**预期输出：**
```
go: downloading github.com/mattn/go-sqlite3 v1.14.17
go: downloading github.com/jinzhu/now v1.1.5
...
```

这个命令会：
- 下载所有缺失的依赖
- 移除未使用的依赖
- 生成/更新 `go.sum` 文件

### 步骤 5: 验证依赖

```bash
go mod verify
```

**预期输出：**
```
all modules verified
```

### 步骤 6: 测试编译

```bash
# Windows
go build -o software-download-center.exe .

# Linux/macOS
go build -o software-download-center .
```

**预期输出：**
- 无错误信息
- 生成可执行文件

### 步骤 7: 运行项目

```bash
# Windows
go run main.go

# 或使用编译后的文件
.\software-download-center.exe

# Linux/macOS
go run main.go

# 或使用编译后的文件
./software-download-center
```

**预期输出：**
```
=============================================
✅ 数据库初始化成功
✅ 配置缓存初始化成功
=============================================
📋 开始注册路由...
✅ 路由注册成功 [GET ] / (类型: view)
...
📋 路由注册完成！

=============================================
✅ 服务器启动成功
📡 访问地址: http://localhost:3355
🌍 当前环境: production
🔄 兼容旧版访问：支持 /tool-status.json /update-info.json /media-types.json
=============================================
```

### 步骤 8: 访问应用

1. **主页**：http://localhost:3355
2. **后台管理**：http://localhost:3355/admin

## 开发模式运行

### 启用调试模式

```bash
# Windows (PowerShell)
$env:GIN_MODE="debug"; go run main.go

# Windows (CMD)
set GIN_MODE=debug && go run main.go

# Linux/macOS
GIN_MODE=debug go run main.go
```

### 自定义端口

```bash
# Windows (PowerShell)
$env:PORT="8080"; go run main.go

# Windows (CMD)
set PORT=8080 && go run main.go

# Linux/macOS
PORT=8080 go run main.go
```

## 编译打包

### 方法 1: 使用打包脚本（推荐）

#### Windows

```bash
# 运行批处理脚本
build.bat
```

#### Linux/macOS

```bash
# 添加执行权限
chmod +x build.sh

# 运行脚本
./build.sh
```

编译后的文件位于 `build/output/` 目录。

### 方法 2: 手动编译

#### 编译当前平台版本

```bash
# Windows
go build -ldflags="-s -w" -o software-download-center.exe .

# Linux
go build -ldflags="-s -w" -o software-download-center .

# macOS
go build -ldflags="-s -w" -o software-download-center .
```

#### 交叉编译（在其他平台编译）

```bash
# 在 Windows 上编译 Linux 版本
set GOOS=linux
set GOARCH=amd64
go build -ldflags="-s -w" -o software-download-center .

# 在 Linux/macOS 上编译 Windows 版本
GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -o software-download-center.exe .

# 在 Linux/macOS 上编译 macOS 版本（Apple Silicon）
GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w" -o software-download-center .
```

**编译参数说明：**
- `-ldflags="-s -w"`：减小可执行文件大小
  - `-s`：去除符号表
  - `-w`：去除调试信息

### 方法 3: 静态编译（无 CGO 依赖）

```bash
# Windows
set CGO_ENABLED=0
set GOOS=windows
set GOARCH=amd64
go build -ldflags="-s -w" -o software-download-center.exe .

# Linux
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o software-download-center .

# macOS
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -ldflags="-s -w" -o software-download-center .
```

**注意：** 静态编译时 SQLite 可能无法使用，需要 CGO 支持。

## 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `PORT` | 服务器端口 | `3355` |
| `GIN_MODE` | Gin 运行模式 | `release` |
| `CGO_ENABLED` | 是否启用 CGO | `1` |

### 文件命名规则

下载文件需要遵循以下命名格式才能被正确识别：

```
产品名称 Setup 版本号.扩展名
```

**示例：**
- `YmhutBox Setup 1.4.21.exe`
- `弈鸣小筑 Setup 2.0.0.zip`

**支持的扩展名：** `.exe`, `.zip`, `.pkg`, `.dmg`, `.msi`

## 后台管理

### 访问地址

http://localhost:3355/admin

### 首次使用

1. 访问后台管理页面
2. 点击"注册"标签
3. 填写注册信息（第一个注册的用户自动成为管理员）
4. 登录后即可使用所有管理功能

### 密码要求

- 至少 8 个字符
- 包含至少一个大写字母
- 包含至少一个小写字母
- 包含至少一个数字
- 包含至少一个特殊字符
- 不能是常见弱密码

详细使用说明请查看 [ADMIN.md](./ADMIN.md)。

## UI/UX 改进

相比 Node.js 版本，Go 版本在 UI/UX 方面做了以下改进：

1. **增强的动画效果**
   - 更流畅的卡片入场动画
   - 改进的悬停效果（轻微上浮）
   - 优化的按钮交互反馈

2. **改进的滚动条**
   - 更宽的滚动条（10px）
   - 圆角设计
   - 平滑的过渡效果

3. **无障碍改进**
   - 支持 `prefers-reduced-motion` 媒体查询
   - 增强的焦点可见性
   - 更好的键盘导航支持

4. **性能优化**
   - Go 的高性能并发处理
   - 更快的响应时间
   - 更低的内存占用

## API 接口

### JSON 接口

- `GET /tool-status.json` - 工具状态配置
- `GET /update-info.json` - 更新信息
- `GET /media-types.json` - 媒体类型配置
- `GET /plugins.json` - 插件配置

所有接口都支持不带 `.json` 后缀的访问方式（向后兼容）。

### 文件下载

- `GET /downloads/:filename` - 下载指定文件

### 静态资源

- `/css/*` - CSS 样式文件
- `/img/*` - 图片资源
- `/fonts/*` - 字体文件
- `/lang/*` - 语言文件

### 后台管理 API

详细 API 文档请查看 [ADMIN.md](./ADMIN.md)。

## 常见问题

### 1. 编译错误：missing go.sum entry

**解决方法：**
```bash
go mod tidy
```

### 2. 运行时错误：数据库初始化失败

**可能原因：**
- `data` 目录权限不足
- 磁盘空间不足

**解决方法：**
- 检查目录权限
- 确保有足够的磁盘空间
- 手动创建 `data` 目录

### 3. 端口被占用

**解决方法：**
```bash
# 使用其他端口
PORT=8080 go run main.go
```

### 4. SQLite 相关错误（CGO 问题）

**错误信息：**
```
SQLite 连接失败: Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work
```

**可能原因：**
- 缺少 CGO 支持
- 缺少 GCC 编译器
- 编译时禁用了 CGO

**解决方法：**

**方案 1: 启用 CGO 重新编译**
```bash
# Windows (PowerShell)
$env:CGO_ENABLED="1"
go build -o software-download-center.exe .

# Linux/macOS
export CGO_ENABLED=1
go build -o software-download-center .
```

**方案 2: 使用 MySQL（无需 CGO）**
```bash
# Windows (PowerShell)
$env:DB_TYPE="mysql"
$env:DB_HOST="localhost"
$env:DB_USER="root"
$env:DB_PASSWORD="password"
$env:DB_NAME="software_download_center"
go run main.go

# Linux/macOS
export DB_TYPE=mysql
export DB_HOST=localhost
export DB_USER=root
export DB_PASSWORD=password
export DB_NAME=software_download_center
go run main.go
```

详细说明请查看 [CGO_FIX.md](./CGO_FIX.md)。

### 5. 依赖下载失败

**解决方法：**
```bash
# 设置 Go 代理（中国大陆）
go env -w GOPROXY=https://goproxy.cn,direct

# 或使用官方代理
go env -w GOPROXY=https://proxy.golang.org,direct
```

## 开发说明

### 添加新路由

在 `config/routes.go` 中的 `RegisterRoutes` 函数中添加新路由。

### 修改模板

模板文件位于 `views/` 目录，使用 Go 的 `html/template` 语法。

### 添加新的工具函数

在 `utils/` 目录下创建新的工具文件。

### 数据库迁移

数据库使用 GORM 自动迁移，启动时会自动创建表结构。

## 部署说明

### 生产环境部署

1. **编译可执行文件**
   ```bash
   go build -ldflags="-s -w" -o software-download-center .
   ```

2. **复制必要文件**
   ```bash
   # 复制静态资源
   cp -r public output/
   cp -r views output/
   ```

3. **运行服务**
   ```bash
   PORT=3355 ./software-download-center
   ```

### 使用进程管理器

详细部署说明请查看 [BUILD.md](./BUILD.md)。

## 与 Node.js 版本的差异

1. **性能**: Go 版本具有更好的并发性能和更低的内存占用
2. **部署**: Go 版本编译为单个可执行文件，部署更简单
3. **UI**: Go 版本包含了一些 UI/UX 改进
4. **功能**: 功能完全一致，100% 兼容
5. **后台管理**: Go 版本新增了完整的后台管理系统

## 快速开始（完整流程）

```bash
# 1. 检查 Go 版本
go version

# 2. 进入项目目录
cd go

# 3. 下载依赖
go mod download

# 4. 整理依赖
go mod tidy

# 5. 验证依赖
go mod verify

# 6. 运行项目
go run main.go

# 7. 访问应用
# 浏览器打开: http://localhost:3355
```

## 许可证

MIT License

## 作者

YMhut

## 相关文档

- [QUICKSTART.md](./QUICKSTART.md) - 快速开始指南（推荐新手）
- [ADMIN.md](./ADMIN.md) - 后台管理系统使用说明
- [BUILD.md](./BUILD.md) - 打包编译详细说明
- [CGO_FIX.md](./CGO_FIX.md) - CGO 问题解决方案（SQLite 相关）