# 快速开始指南

这是一个详细的、一步一步的安装和运行指南。

## 第一步：检查 Go 环境

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

```bash
go version
```

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

**如果显示错误：**
- 请先安装 Go：https://golang.org/dl/
- 安装后重启终端

---

## 第二步：进入项目目录

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

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

**验证：** 运行 `dir` (Windows) 或 `ls` (Linux/macOS) 应该能看到 `main.go` 和 `go.mod` 文件。

---

## 第三步：下载依赖

```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
go: downloading gorm.io/driver/sqlite v1.5.4
go: downloading golang.org/x/crypto v0.17.0
...
```

**如果下载失败：**
```bash
# 设置 Go 代理（中国大陆用户）
go env -w GOPROXY=https://goproxy.cn,direct

# 然后重新运行
go mod download
```

---

## 第四步：整理依赖（生成 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: downloading github.com/jinzhu/inflection v1.0.0
...
```

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

---

## 第五步：验证依赖

```bash
go mod verify
```

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

如果显示错误，请重新运行 `go mod tidy`。

---

## 第六步：测试编译

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

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

**预期结果：**
- ✅ 无错误信息
- ✅ 生成可执行文件（`software-download-center.exe` 或 `software-download-center`）

**如果编译失败：**
- 检查错误信息
- 确保所有依赖都已下载（重新运行 `go mod tidy`）

---

## 第七步：运行项目

### 方法 1: 直接运行（开发模式）

```bash
# Windows
go run main.go

# Linux/macOS
go run main.go
```

### 方法 2: 使用编译后的文件

```bash
# Windows
.\software-download-center.exe

# Linux/macOS
./software-download-center
```

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

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

---

## 第八步：访问应用

1. **打开浏览器**
2. **访问主页**：http://localhost:3355
3. **访问后台管理**：http://localhost:3355/admin

---

## 常见问题解决

### 问题 1: `missing go.sum entry`

**错误信息：**
```
missing go.sum entry for module providing package github.com/gin-gonic/gin
```

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

---

### 问题 2: 依赖下载失败

**错误信息：**
```
go: github.com/gin-gonic/gin@v1.9.1: Get "https://proxy.golang.org/...": dial tcp: lookup proxy.golang.org: no such host
```

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

# 重新下载
go mod download
go mod tidy
```

---

### 问题 3: 编译错误

**错误信息：**
```
# software-download-center/utils
utils\route-utils.go:51:29: invalid operation
```

**解决方法：**
```bash
# 清理并重新编译
go clean
go mod tidy
go build -o software-download-center.exe .
```

---

### 问题 4: 端口被占用

**错误信息：**
```
listen tcp :3355: bind: address already in use
```

**解决方法：**
```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
```

---

### 问题 5: 数据库初始化失败

**错误信息：**
```
数据库初始化失败: open data/app.db: The system cannot find the path specified
```

**解决方法：**
```bash
# 手动创建 data 目录
# Windows
mkdir data

# Linux/macOS
mkdir -p data

# 然后重新运行
go run main.go
```

---

## 完整命令清单（复制粘贴）

### Windows (PowerShell)

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

# 2. 进入项目目录
cd D:\Desktop\update\go

# 3. 下载依赖
go mod download

# 4. 整理依赖
go mod tidy

# 5. 验证依赖
go mod verify

# 6. 测试编译
go build -o software-download-center.exe .

# 7. 运行项目
go run main.go
```

### Windows (CMD)

```cmd
REM 1. 检查 Go 版本
go version

REM 2. 进入项目目录
cd D:\Desktop\update\go

REM 3. 下载依赖
go mod download

REM 4. 整理依赖
go mod tidy

REM 5. 验证依赖
go mod verify

REM 6. 测试编译
go build -o software-download-center.exe .

REM 7. 运行项目
go run main.go
```

### Linux/macOS

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

# 2. 进入项目目录
cd /path/to/update/go

# 3. 下载依赖
go mod download

# 4. 整理依赖
go mod tidy

# 5. 验证依赖
go mod verify

# 6. 测试编译
go build -o software-download-center .

# 7. 运行项目
go run main.go
```

---

## 下一步

- 📖 查看 [README.md](./README.md) 了解完整功能
- 🔧 查看 [ADMIN.md](./ADMIN.md) 了解后台管理
- 📦 查看 [BUILD.md](./BUILD.md) 了解打包部署

---

## 需要帮助？

如果遇到问题：
1. 检查 Go 版本：`go version`（需要 >= 1.21）
2. 检查网络连接（下载依赖需要）
3. 查看错误信息并参考上面的"常见问题解决"
4. 运行 `go mod tidy` 重新整理依赖