460 lines
8.4 KiB
Markdown
460 lines
8.4 KiB
Markdown
# 快速开始指南
|
||
|
||
本文档将指导你完成 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 到项目仓库。
|