LandPPT/docs/base_url_configuration.md

反向代理域名配置指南

当您为LandPPT主服务设置了反向代理域名时，需要配置base_url参数以确保图床服务的链接能够正确显示。

问题描述

在使用反向代理（如Nginx、Apache等）时，如果没有正确配置base_url，会出现以下问题：

• 图片链接仍然显示为localhost:8000
• 前端无法正确加载图片
• 图片预览、下载等功能异常

解决方案

1. 通过Web界面配置

1. 访问系统配置页面：https://your-domain.com/ai-config
2. 切换到"应用配置"标签页
3. 在"基础URL (BASE_URL)"字段中输入您的代理域名
4. 例如：https://your-domain.com 或 http://your-domain.com:8080
5. 点击"保存应用配置"

2. 通过环境变量配置

在.env文件中添加或修改：

# 基础URL配置 - 用于生成图片等资源的绝对URL
BASE_URL=https://your-domain.com

3. 通过命令行参数配置

启动服务时指定：

BASE_URL=https://your-domain.com python -m uvicorn src.landppt.main:app --host 0.0.0.0 --port 8000

配置示例

Nginx反向代理配置示例

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost: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;
    }
}

对应的LandPPT配置：

BASE_URL=http://your-domain.com

HTTPS反向代理配置示例

server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/your/cert.pem;
    ssl_certificate_key /path/to/your/key.pem;
    
    location / {
        proxy_pass http://localhost: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 https;
    }
}

对应的LandPPT配置：

BASE_URL=https://your-domain.com

验证配置

配置完成后，您可以通过以下方式验证：

1. 检查图片URL：在PPT编辑器中生成或上传图片，查看图片URL是否使用了正确的域名
2. 测试图片访问：直接访问图片URL，确认能够正常显示
3. 检查API响应：调用图片相关API，查看返回的URL是否正确

技术实现

系统通过以下方式实现统一的URL管理：

1. URL服务：src/landppt/services/url_service.py - 统一管理所有URL生成逻辑
2. 配置集成：自动从配置服务获取base_url设置
3. 实时更新：配置更改后立即生效，无需重启服务
4. 向后兼容：如果未配置base_url，自动使用http://localhost:8000作为默认值

注意事项

1. URL格式：base_url不能以斜杠(/)结尾
2. 协议匹配：确保base_url的协议（http/https）与实际访问协议一致
3. 端口配置：如果使用非标准端口，需要在base_url中包含端口号
4. 配置优先级：环境变量 > Web界面配置 > 默认值

故障排除

图片仍然显示localhost

1. 检查base_url配置是否正确
2. 确认配置已保存并生效
3. 清除浏览器缓存
4. 检查反向代理配置

图片无法加载

1. 确认反向代理正确转发了/api/image/路径
2. 检查防火墙和安全组设置
3. 验证SSL证书配置（如果使用HTTPS）

配置不生效

1. 重启LandPPT服务
2. 检查环境变量是否正确设置
3. 查看服务日志中的配置加载信息