first commit

2026-02-13 15:57:29 +08:00
commit aacda0b66a
53 changed files with 10029 additions and 0 deletions
--- a/docs/development/getting-started.md
+++ b/docs/development/getting-started.md
@@ -0,0 +1,459 @@
+# 快速开始指南
+
+本文档将指导你完成 Web Rust Template 项目的安装、配置和运行。
+
+## 目录
+
+- [环境要求](#环境要求)
+- [安装步骤](#安装步骤)
+- [配置说明](#配置说明)
+- [运行项目](#运行项目)
+- [验证安装](#验证安装)
+- [常见问题](#常见问题)
+
+---
+
+## 环境要求
+
+### 必需环境
+
+- **Rust**：1.70 或更高版本
+  - 安装方法：访问 [rustup.rs](https://rustup.rs/) 或使用 `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+- **Git**：用于克隆项目
+
+### 数据库（任选其一）
+
+- **SQLite**：默认选项，无需额外安装
+- **MySQL**：5.7 或更高版本
+- **PostgreSQL**：12 或更高版本
+
+### 可选环境
+
+- **Redis**：用于存储 Refresh Token（推荐）
+  - Windows：下载 [Redis for Windows](https://github.com/microsoftarchive/redis/releases)
+  - macOS：`brew install redis`
+  - Linux：`sudo apt-get install redis-server`
+
+### 检查环境
+
+```bash
+# 检查 Rust 版本
+rustc --version
+
+# 检查 Cargo 版本
+cargo --version
+
+# 检查 Git 版本
+git --version
+
+# 检查 MySQL（如果使用）
+mysql --version
+
+# 检查 PostgreSQL（如果使用）
+psql --version
+
+# 检查 Redis（如果使用）
+redis-cli --version
+```
+
+---
+
+## 安装步骤
+
+### 1. 克隆项目
+
+```bash
+git clone <repository-url>
+cd web-rust-template
+```
+
+### 2. 安装依赖
+
+使用 Cargo 构建项目（会自动下载依赖）：
+
+```bash
+cargo build
+```
+
+### 3. 配置项目
+
+#### 方式一：使用默认配置（SQLite，最简单）
+
+**无需任何配置！** 直接运行即可：
+
+```bash
+cargo run
+```
+
+默认配置：
+- 数据库：SQLite（自动创建 `db.sqlite3`）
+- 服务器：`127.0.0.1:3000`
+- Redis：`localhost:6379`
+
+#### 方式二：使用 MySQL/PostgreSQL
+
+**步骤 1**：复制对应的配置文件
+
+```bash
+# 使用 MySQL
+cp config/development.mysql.toml config/local.toml
+
+# 或使用 PostgreSQL
+cp config/development.postgresql.toml config/local.toml
+```
+
+**步骤 2**：修改配置文件
+
+编辑 `config/local.toml`，修改数据库连接信息：
+
+```toml
+[database]
+# MySQL 配置
+host = "localhost"
+port = 3306
+user = "root"
+password = "your-password"
+database = "web_template_dev"
+
+# 或 PostgreSQL 配置
+# host = "localhost"
+# port = 5432
+# user = "postgres"
+# password = "your-password"
+# database = "web_template_dev"
+```
+
+**步骤 3**：运行项目
+
+```bash
+# 使用指定配置文件运行
+cargo run -- -c config/local.toml
+```
+
+#### 方式三：通过环境变量覆盖（适用于 Docker/Kubernetes）
+
+```bash
+# 使用环境变量
+DATABASE_TYPE=postgresql \
+DATABASE_HOST=localhost \
+DATABASE_PORT=5432 \
+DATABASE_USER=postgres \
+DATABASE_PASSWORD=password \
+DATABASE_DATABASE=web_template_dev \
+cargo run
+```
+
+---
+
+## 配置说明
+
+### 数据库配置
+
+#### SQLite（默认，推荐用于开发）
+
+**优点**：无需额外安装，文件存储，易于测试
+
+**缺点**：不支持高并发写入
+
+**适用场景**：开发环境、小型应用
+
+**使用方法**：无需配置，直接运行
+
+#### MySQL
+
+**优点**：成熟稳定，支持高并发
+
+**缺点**：需要额外安装和配置
+
+**适用场景**：生产环境、大型应用
+
+**配置方法**：
+
+**选项 1**：修改配置文件
+
+```bash
+# 复制 MySQL 配置模板
+cp config/development.mysql.toml config/local.toml
+
+# 编辑 config/local.toml，修改数据库连接信息
+```
+
+**选项 2**：使用环境变量
+
+```bash
+DATABASE_TYPE=mysql \
+DATABASE_HOST=localhost \
+DATABASE_PORT=3306 \
+DATABASE_USER=root \
+DATABASE_PASSWORD=your-password \
+DATABASE_DATABASE=web_template_dev \
+cargo run
+```
+
+#### PostgreSQL
+
+**优点**：功能强大，支持高级特性
+
+**缺点**：资源占用较大
+
+**适用场景**：需要高级数据库功能的应用
+
+**配置方法**：与 MySQL 类似，使用 `config/development.postgresql.toml` 或环境变量
+
+### 认证配置
+
+**开发环境**：使用默认配置即可（JWT 密钥已在配置文件中）
+
+**生产环境**：必须修改配置文件中的 JWT 密钥
+
+```toml
+[auth]
+# 生产环境必须使用强密钥
+jwt_secret = "Kx7Yn2Zp9qR8wF4tL6mN3vB5xC8zD1sE9aH2jK7"
+```
+
+生成强密钥：
+```bash
+openssl rand -base64 32
+```
+
+### Redis 配置
+
+**开发环境**：默认连接 `localhost:6379`，无需配置
+
+**生产环境**：修改配置文件或设置环境变量
+
+```bash
+REDIS_HOST=your-redis-host \
+REDIS_PORT=6379 \
+REDIS_PASSWORD=your-password \
+cargo run
+```
+
+---
+
+## 运行项目
+
+### 开发模式
+
+**使用默认配置（SQLite）**：
+```bash
+cargo run
+```
+
+**使用指定配置文件**：
+```bash
+cargo run -- -c config/development.mysql.toml
+```
+
+**使用环境变量**：
+```bash
+DATABASE_TYPE=mysql DATABASE_HOST=localhost cargo run
+```
+
+### 指定环境
+
+```bash
+# 开发环境
+cargo run -- -e development
+
+# 生产环境
+cargo run -- -e production
+```
+
+### 后台运行（生产环境）
+
+```bash
+# 使用 nohup
+nohup cargo run -- -e production > app.log 2>&1 &
+
+# 使用 screen
+screen -S web-rust-template
+cargo run -- -e production
+# 按 Ctrl+A 然后 D 分离会话
+```
+
+---
+
+## 验证安装
+
+### 1. 健康检查
+
+```bash
+curl http://localhost:3000/health
+```
+
+预期响应：
+```json
+{
+  "status": "ok"
+}
+```
+
+### 2. 服务器信息
+
+```bash
+curl http://localhost:3000/info
+```
+
+预期响应：
+```json
+{
+  "name": "web-rust-template",
+  "version": "0.1.0",
+  "status": "running",
+  "timestamp": 1704112800
+}
+```
+
+### 3. 用户注册
+
+```bash
+curl -X POST http://localhost:3000/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "test@example.com",
+    "password": "password123"
+  }'
+```
+
+预期响应：
+```json
+{
+  "code": 200,
+  "message": "Success",
+  "data": {
+    "email": "test@example.com",
+    "created_at": "2026-02-13T12:00:00.000Z",
+    "access_token": "eyJhbGciOiJIUzI1NiIs...",
+    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
+  }
+}
+```
+
+### 4. 用户登录
+
+```bash
+curl -X POST http://localhost:3000/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "test@example.com",
+    "password": "password123"
+  }'
+```
+
+预期响应：
+```json
+{
+  "code": 200,
+  "message": "Success",
+  "data": {
+    "id": "1234567890",
+    "email": "test@example.com",
+    "created_at": "2026-02-13T12:00:00.000Z",
+    "access_token": "eyJhbGciOiJIUzI1NiIs...",
+    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
+  }
+}
+```
+
+---
+
+## 常见问题
+
+### 1. 端口被占用
+
+**错误信息**：`Os { code: 10048, kind: AddrInUse }` 或 `Address already in use`
+
+**解决方案**：
+
+**选项 1**：修改配置文件中的端口
+
+```toml
+[server]
+port = 3001
+```
+
+**选项 2**：通过环境变量覆盖
+
+```bash
+SERVER_PORT=3001 cargo run
+```
+
+**选项 3**：停止占用端口的进程
+
+```bash
+# Windows
+netstat -ano | findstr :3000
+taskkill /PID <pid> /F
+
+# macOS/Linux
+lsof -ti:3000 | xargs kill -9
+```
+
+### 2. 数据库连接失败
+
+**错误信息**：`Database connection failed`
+
+**解决方案**：
+
+- 检查数据库服务是否启动
+- 检查配置文件中的数据库配置是否正确
+- 确认数据库用户权限
+- SQLite：检查是否有写入权限
+
+### 3. Redis 连接失败
+
+**错误信息**：`Redis 连接失败`
+
+**解决方案**：
+
+- 检查 Redis 服务是否启动：`redis-cli ping`
+- 检查配置文件中的 Redis 配置是否正确
+- 如果不需要 Redis 功能，可以暂时禁用（需要修改代码）
+
+### 4. 编译错误
+
+**错误信息**：`error: linking with link.exe failed`
+
+**解决方案**：
+
+- Windows 用户需要安装 [C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
+- 或使用 `cargo install cargo-vcpkg` 安装依赖
+
+### 5. 权限错误
+
+**错误信息**：`Permission denied`
+
+**解决方案**：
+
+```bash
+# Linux/macOS
+chmod +x target/debug/web-rust-template
+
+# 或使用 sudo 运行（不推荐生产环境）
+sudo cargo run
+```
+
+---
+
+## 下一步
+
+安装成功后，你可以：
+
+1. 阅读 [API 接口文档](../api/api-overview.md) 了解所有可用的 API
+2. 查看 [项目结构详解](project-structure.md) 了解代码组织
+3. 学习 [DDD 架构规范](ddd-architecture.md) 了解设计原则
+4. 参考 [前端集成示例](../api/examples/frontend-integration.md) 集成前端应用
+
+---
+
+## 相关文档
+
+- [配置文件详解](../deployment/configuration.md) - 配置文件组织说明
+- [环境变量配置](../deployment/environment-variables.md) - 完整的环境变量列表
+- [API 接口文档](../api/api-overview.md) - 完整的 API 接口说明
+
+---
+
+**提示**：遇到问题？查看 [常见问题](#常见问题) 或提交 Issue 到项目仓库。