Kevi Blog 开发文档

简体中文

English

简体中文

English

Appearance

环境配置 ​

环境变量配置 ​

项目使用 .env 文件管理环境变量。在项目根目录创建 .env 文件，参考 .env.example 进行配置。

bash
# 复制环境变量模板
cp .env.example .env

完整环境变量说明 ​

数据库配置 ​

变量名说明默认值必填
DB_HOST数据库主机地址localhost是
DB_PORT数据库端口3306是
DB_USER数据库用户名root是
DB_PASSWORD数据库密码-是
DB_NAME数据库名称nuxt_blog是
env
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=nuxt_blog

Redis 配置 ​

变量名说明默认值必填
REDIS_URLRedis 连接地址redis://localhost:6379是
REDIS_PASSWORDRedis 密码-否
CACHE_STORAGE缓存存储方式 (redis 或 file)redis否
env
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=redispassword
CACHE_STORAGE=redis

注意:

  • CACHE_STORAGE 设置为 file 时，缓存将存储在文件系统中
  • 推荐生产环境使用 redis 以获得更好的性能

JWT 认证配置 ​

变量名说明默认值必填
JWT_SECRETJWT 签名密钥-是
JWT_EXPIRES_INToken 过期时间7d否
env
JWT_SECRET=your_jwt_secret_key_here_please_change_in_production
JWT_EXPIRES_IN=7d

⚠️ 重要提示:

  • JWT_SECRET 必须是随机且保密的字符串
  • 生产环境务必使用强密码
  • JWT_EXPIRES_IN 支持格式: 7d, 24h, 60m, 3600s 等

文件存储配置 ​

本地存储 ​

env
# 使用本地文件系统存储
# 无需额外配置，文件存储在 ./uploads 目录

S3 兼容存储（MinIO/阿里云 OSS/腾讯云 COS 等） ​

env
# AWS S3 / MinIO
STORAGE_TYPE=s3
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your_access_key
S3_SECRET_ACCESS_KEY=your_secret_key
S3_BUCKET_NAME=uploads
S3_ENDPOINT=https://s3.example.com

# 或使用 MinIO
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_BUCKET_NAME=uploads
S3_ENDPOINT=http://localhost:9000
S3_USE_SSL=false

邮件配置（可选） ​

用于发送密码重置邮件等功能。

env
# SMTP 邮件配置
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_email@gmail.com
SMTP_PASSWORD=your_app_password
SMTP_FROM=noreply@yourdomain.com

应用配置 ​

变量名说明默认值
PORT应用端口3000
HOST监听地址0.0.0.0
NODE_ENV运行环境development
env
PORT=3000
HOST=0.0.0.0
NODE_ENV=production

配置示例 ​

开发环境 ​

env
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=root
DB_NAME=nuxt_blog_dev

# Redis配置
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=
CACHE_STORAGE=redis

# JWT配置
JWT_SECRET=dev_jwt_secret_key
JWT_EXPIRES_IN=7d

# 应用配置
PORT=3000
NODE_ENV=development

生产环境 ​

env
# 数据库配置
DB_HOST=your-production-db-host
DB_PORT=3306
DB_USER=your_db_user
DB_PASSWORD=strong_password_here
DB_NAME=nuxt_blog

# Redis配置
REDIS_URL=redis://your-redis-host:6379
REDIS_PASSWORD=strong_redis_password
CACHE_STORAGE=redis

# JWT配置
JWT_SECRET=very_strong_random_secret_key_at_least_32_chars
JWT_EXPIRES_IN=7d

# S3存储配置
STORAGE_TYPE=s3
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your_aws_access_key
S3_SECRET_ACCESS_KEY=your_aws_secret_key
S3_BUCKET_NAME=your-bucket-name
S3_ENDPOINT=https://s3.amazonaws.com

# 邮件配置
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=noreply@yourdomain.com
SMTP_PASSWORD=your_app_password
SMTP_FROM=noreply@yourdomain.com

# 应用配置
PORT=3000
HOST=0.0.0.0
NODE_ENV=production

Docker 环境配置 ​

如果使用 Docker 部署，需要修改 Redis 配置以连接容器内的 Redis 服务：

env
# Redis配置（Docker环境）
REDIS_URL=redis://redis:6379
REDIS_PASSWORD=redispassword

配置验证 ​

配置完成后，可以使用以下命令验证配置是否正确：

bash
# 启动开发服务器
pnpm run dev

# 查看日志，确认数据库和 Redis 连接成功

常见问题 ​

1. 数据库连接失败 ​

检查以下几点：

  • MySQL 服务是否正在运行
  • 用户名和密码是否正确
  • 数据库是否已创建
  • 防火墙是否允许连接

2. Redis 连接失败 ​

  • 确保 Redis 服务正在运行
  • 检查 Redis 密码是否正确
  • 确认端口没有被防火墙阻止

3. JWT_SECRET 未设置 ​

  • 确保 .env 文件中已设置 JWT_SECRET
  • 生产环境必须使用强随机字符串

4. 文件上传失败 ​

  • 检查存储配置是否正确
  • 确保上传目录有写入权限（本地存储）
  • 检查 S3/MinIO 配置是否正确（云存储）

安全建议 ​

  1. 永远不要将 .env 文件提交到版本控制
  2. 生产环境必须使用强密码
  3. 定期更换密钥和密码
  4. 使用环境变量管理工具（如 Docker Secrets、Vault 等）
  5. 限制数据库和 Redis 的访问权限