web-rust-template-project/docs/development/getting-started.md

快速开始指南

本文档将指导你完成 Web Rust Template 项目的安装、配置和运行。

目录

• 环境要求
• 安装步骤
• 配置说明
• 运行项目
• 验证安装
• 常见问题

---

环境要求

必需环境

• Rust：1.70 或更高版本
  • 安装方法：访问 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
  • macOS：brew install redis
  • Linux：sudo apt-get install redis-server

检查环境

# 检查 Rust 版本
rustc --version

# 检查 Cargo 版本
cargo --version

# 检查 Git 版本
git --version

# 检查 MySQL（如果使用）
mysql --version

# 检查 PostgreSQL（如果使用）
psql --version

# 检查 Redis（如果使用）
redis-cli --version

---

安装步骤

1. 克隆项目

git clone <repository-url>
cd web-rust-template

2. 安装依赖

使用 Cargo 构建项目（会自动下载依赖）：

cargo build

3. 配置项目

方式一：使用默认配置（SQLite，最简单）

无需任何配置！ 直接运行即可：

cargo run

默认配置：

• 数据库：SQLite（自动创建 db.sqlite3）
• 服务器：127.0.0.1:3000
• Redis：localhost:6379

方式二：使用 MySQL/PostgreSQL

步骤 1：复制对应的配置文件

# 使用 MySQL
cp config/development.mysql.toml config/local.toml

# 或使用 PostgreSQL
cp config/development.postgresql.toml config/local.toml

步骤 2：修改配置文件

编辑 config/local.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：运行项目

# 使用指定配置文件运行
cargo run -- -c config/local.toml

方式三：通过环境变量覆盖（适用于 Docker/Kubernetes）

# 使用环境变量
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：修改配置文件

# 复制 MySQL 配置模板
cp config/development.mysql.toml config/local.toml

# 编辑 config/local.toml，修改数据库连接信息

选项 2：使用环境变量

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 密钥

[auth]
# 生产环境必须使用强密钥
jwt_secret = "Kx7Yn2Zp9qR8wF4tL6mN3vB5xC8zD1sE9aH2jK7"

生成强密钥：

openssl rand -base64 32

Redis 配置

开发环境：默认连接 localhost:6379，无需配置

生产环境：修改配置文件或设置环境变量

REDIS_HOST=your-redis-host \
REDIS_PORT=6379 \
REDIS_PASSWORD=your-password \
cargo run

---

运行项目

开发模式

使用默认配置（SQLite）：

cargo run

使用指定配置文件：

cargo run -- -c config/development.mysql.toml

使用环境变量：

DATABASE_TYPE=mysql DATABASE_HOST=localhost cargo run

指定环境

# 开发环境
cargo run -- -e development

# 生产环境
cargo run -- -e production

后台运行（生产环境）

# 使用 nohup
nohup cargo run -- -e production > app.log 2>&1 &

# 使用 screen
screen -S web-rust-template
cargo run -- -e production
# 按 Ctrl+A 然后 D 分离会话

---

验证安装

1. 健康检查

curl http://localhost:3000/health

预期响应：

{
  "status": "ok"
}

2. 服务器信息

curl http://localhost:3000/info

预期响应：

{
  "name": "web-rust-template",
  "version": "0.1.0",
  "status": "running",
  "timestamp": 1704112800
}

3. 用户注册

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123"
  }'

预期响应：

{
  "code": 200,
  "message": "Success",
  "data": {
    "email": "test@example.com",
    "created_at": "2026-02-13T12:00:00.000Z",
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

4. 用户登录

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123"
  }'

预期响应：

{
  "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：修改配置文件中的端口

[server]
port = 3001

选项 2：通过环境变量覆盖

SERVER_PORT=3001 cargo run

选项 3：停止占用端口的进程

# 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
• 或使用 cargo install cargo-vcpkg 安装依赖

5. 权限错误

错误信息：Permission denied

解决方案：

# Linux/macOS
chmod +x target/debug/web-rust-template

# 或使用 sudo 运行（不推荐生产环境）
sudo cargo run

---

下一步

安装成功后，你可以：

1. 阅读 API 接口文档 了解所有可用的 API
2. 查看 项目结构详解 了解代码组织
3. 学习 DDD 架构规范 了解设计原则
4. 参考 前端集成示例 集成前端应用

---

相关文档

• 配置文件详解 - 配置文件组织说明
• 环境变量配置 - 完整的环境变量列表
• API 接口文档 - 完整的 API 接口说明

---

提示：遇到问题？查看 常见问题 或提交 Issue 到项目仓库。