前端配置指南

环境变量配置

快速开始

复制环境配置文件：

cd frontend
cp .env.development .env

配置项说明

HTTPS 开关（新增）

通过 VITE_ENABLE_HTTPS 环境变量控制是否启用 HTTPS：

# 启用 HTTPS（默认，推荐开发环境使用）
VITE_ENABLE_HTTPS=true

# 禁用 HTTPS（使用 HTTP 模式）
VITE_ENABLE_HTTPS=false

说明：

设置为 true 时：启用 HTTPS，需要提供有效的 SSL 证书
设置为 false 时：使用 HTTP 模式，无需证书
开发环境建议启用 HTTPS，否则浏览器会限制麦克风访问

WebSocket URL配置

生产环境 (.env.production):

# 通过Nginx域名访问
VITE_WS_URL=wss://www.hikelly.chat/ws

开发环境 (.env.development):

# 本地HTTPS访问
VITE_WS_URL=wss://localhost:8000/ws

# 或本地HTTP（不推荐，浏览器会限制麦克风）
# VITE_WS_URL=ws://localhost:8000/ws

局域网测试:

# 替换为实际IP地址
VITE_WS_URL=wss://192.168.2.112:8000/ws

SSL证书配置

开发环境:

# 启用 HTTPS
VITE_ENABLE_HTTPS=true

# 证书路径留空，自动使用 ../ssl/ 的自签名证书
VITE_SSL_KEYFILE=
VITE_SSL_CERTFILE=

生产环境:

# 使用Nginx管理证书，前端不需要配置
VITE_ENABLE_HTTPS=false
VITE_SSL_KEYFILE=
VITE_SSL_CERTFILE=

禁用 HTTPS（仅测试）:

# 使用 HTTP 模式
VITE_ENABLE_HTTPS=false

启动服务

cd frontend
npm run dev

HTTPS 配置逻辑

检查 HTTPS 开关：VITE_ENABLE_HTTPS 必须设置为 true
确定证书路径：
- 优先使用 VITE_SSL_KEYFILE 和 VITE_SSL_CERTFILE（生产）
- 未配置则使用 ../ssl/key.pem 和 ../ssl/cert.pem（开发）
验证证书文件：检查证书文件是否存在
启动模式：
- VITE_ENABLE_HTTPS=true + 证书存在 → HTTPS 模式
- VITE_ENABLE_HTTPS=true + 证书不存在 → HTTP 模式（警告）
- VITE_ENABLE_HTTPS=false → HTTP 模式

生产环境部署（推荐）

生产环境建议使用Nginx托管静态文件，而非直接运行Vite dev server：

1. 构建前端

cd frontend
npm run build

2. Nginx配置

server {
    listen 443 ssl;
    server_name www.hikelly.chat;
    
    ssl_certificate /etc/nginx/cert/www.hikelly.chat.pem;
    ssl_certificate_key /etc/nginx/cert/www.hikelly.chat.key;
    
    # 前端静态文件
    location / {
        root /path/to/Lyrria/frontend/dist;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
    
    # 后端API代理
    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    # WebSocket代理
    location /ws {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

使用Nginx时，前后端都不需要配置SSL，证书统一由Nginx管理。

SSL_CONFIG.md 3.4 KB Cronologia Originale