Add File

docs/base_url_configuration.md

@@ -0,0 +1,131 @@
+# 反向代理域名配置指南
+
+当您为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`文件中添加或修改：
+
+```bash
+# 基础URL配置 - 用于生成图片等资源的绝对URL
+BASE_URL=https://your-domain.com
+```
+
+### 3. 通过命令行参数配置
+
+启动服务时指定：
+
+```bash
+BASE_URL=https://your-domain.com python -m uvicorn src.landppt.main:app --host 0.0.0.0 --port 8000
+```
+
+## 配置示例
+
+### Nginx反向代理配置示例
+
+```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配置：
+```bash
+BASE_URL=http://your-domain.com
+```
+
+### HTTPS反向代理配置示例
+
+```nginx
+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配置：
+```bash
+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. 查看服务日志中的配置加载信息