Files

万物街 127a4db1e3 feat: 完成sys模块迁移，对齐PHP/Java框架

- 重构sys模块架构，严格按admin/api/core分层
- 对齐所有sys实体与数据库表结构
- 实现完整的adminapi控制器，匹配PHP/Java契约
- 修复依赖注入问题，确保服务正确注册
- 添加自动迁移工具和契约验证
- 完善多租户支持和审计功能
- 统一命名规范，与PHP业务逻辑保持一致

2025-09-21 21:29:28 +08:00

5.3 KiB

Raw Blame History

WWJCloud Backend 配置设置指南

📋 概述

本文档说明如何设置 WWJCloud Backend 的环境变量配置。

🚀 快速开始

1. 复制配置文件

# 复制示例配置文件
cp env.example .env

# 或者复制特定环境的配置
cp env.development .env  # 开发环境
cp env.production .env   # 生产环境

2. 修改配置

根据你的实际环境修改 .env 文件中的配置项。

📁 配置文件说明

配置文件类型

env.example - 配置示例文件（包含所有配置项）
env.development - 开发环境配置
env.production - 生产环境配置
.env - 实际使用的配置文件（需要手动创建）

配置优先级

环境变量 (最高优先级)
默认配置 (最低优先级)

🔧 必需配置项

应用基础配置

# 应用名称
APP_NAME=WWJCloud Backend

# 应用端口
PORT=3000

# 运行环境
NODE_ENV=development  # development, production, test

数据库配置

# 数据库主机
DB_HOST=localhost

# 数据库端口
DB_PORT=3306

# 数据库用户名
DB_USERNAME=root

# 数据库密码
DB_PASSWORD=your_password

# 数据库名称
DB_DATABASE=wwjcloud

# 是否同步数据库结构（生产环境必须为 false）
DB_SYNC=false

# 是否启用数据库日志
DB_LOGGING=false

Redis 配置

# Redis 主机
REDIS_HOST=localhost

# Redis 端口
REDIS_PORT=6379

# Redis 密码
REDIS_PASSWORD=

# Redis 数据库编号
REDIS_DB=0

# Redis 键前缀
REDIS_KEY_PREFIX=wwjcloud:

JWT 配置

# JWT 密钥（生产环境必须修改）
JWT_SECRET=your-super-secret-jwt-key

# JWT 过期时间
JWT_EXPIRES_IN=7d

# JWT 算法
JWT_ALGORITHM=HS256

🌍 环境特定配置

开发环境

# 复制开发环境配置
cp env.development .env

# 主要特点：
# - 启用详细日志 (LOG_LEVEL=debug)
# - 启用数据库日志 (DB_LOGGING=true)
# - 使用本地服务 (localhost)
# - 启用调试工具 (DEBUG_ENABLED=true)

生产环境

# 复制生产环境配置
cp env.production .env

# 主要特点：
# - 关闭详细日志 (LOG_LEVEL=warn)
# - 关闭数据库日志 (DB_LOGGING=false)
# - 使用生产服务器
# - 关闭调试工具 (DEBUG_ENABLED=false)
# - 启用监控 (PROMETHEUS_ENABLED=true)

🔐 安全配置

生产环境安全要求

修改所有密钥

JWT_SECRET=your-super-secret-jwt-key-at-least-32-characters
SESSION_SECRET=production-session-secret-key
COOKIE_SECRET=production-cookie-secret-key

设置强密码

DB_PASSWORD=your-strong-database-password
REDIS_PASSWORD=your-strong-redis-password

配置 CORS
```
CORS_ORIGIN=https://your-domain.com
```

设置域名白名单

ALLOWED_DOMAINS=your-domain.com,api.your-domain.com

📊 监控配置

启用监控

# 启用指标收集
METRICS_ENABLED=true
METRICS_PORT=9090

# 启用 Prometheus 监控
PROMETHEUS_ENABLED=true

# 启用健康检查
HEALTH_CHECK_ENABLED=true
HEALTH_CHECK_INTERVAL=30000

追踪配置

# 启用分布式追踪
TRACING_ENABLED=true

# Jaeger 端点
JAEGER_ENDPOINT=http://jaeger:14268/api/traces

🔄 动态配置

启用动态配置

# 启用动态配置功能
ENABLE_DYNAMIC_CONFIG=true

# 配置缓存时间
CONFIG_CACHE_TTL=300

动态配置示例

通过 API 接口管理动态配置：

# 设置邮件配置
curl -X POST http://localhost:3000/adminapi/config/dynamic \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "key": "email.smtp",
    "value": {
      "host": "smtp.gmail.com",
      "port": 587,
      "secure": false
    },
    "description": "SMTP 服务器配置",
    "category": "email",
    "isPublic": false
  }'

🧪 测试配置

验证配置

# 启动应用后访问配置验证接口
curl http://localhost:3000/adminapi/config/validate

# 查看系统配置
curl http://localhost:3000/adminapi/config/system

配置检查清单

数据库连接正常
Redis 连接正常
JWT 密钥已设置
日志级别合适
文件上传路径存在
第三方服务配置正确

🚨 常见问题

1. 配置不生效

问题：修改了 .env 文件但配置没有生效

解决：

确保 .env 文件在项目根目录
重启应用
检查环境变量名称是否正确

2. 数据库连接失败

问题：无法连接到数据库

解决：

检查 DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD
确保数据库服务正在运行
检查防火墙设置

3. Redis 连接失败

问题：无法连接到 Redis

解决：

检查 REDIS_HOST、REDIS_PORT、REDIS_PASSWORD
确保 Redis 服务正在运行
检查 Redis 配置

4. JWT 错误

问题：JWT 相关错误

解决：

确保 JWT_SECRET 已设置且足够复杂
检查 JWT_EXPIRES_IN 格式
验证 JWT_ALGORITHM 设置

📚 相关文档

🤝 支持

如果遇到配置问题，请：

检查本文档的常见问题部分
查看应用日志
使用配置验证接口检查配置
联系技术支持团队

5.3 KiB Raw Blame History Unescape Escape