# OpenCode + Nginx 集成文档

## 🎯 架构概述

本项目实现了 OpenResty + OpenCode 的安全集成，提供：

```
用户请求 → Nginx (7860, Basic Auth) → OpenCode (57860, 内部)
```

## 🔧 核心组件

### 1. OpenResty Nginx (端口 7860)
- **认证保护**: HTTP Basic Auth (admin/admin123)
- **Lua 安全**: 用户代理过滤
- **API 代理**: 安全转发到 OpenCode
- **静态服务**: HTML 页面

### 2. OpenCode 服务器 (端口 57860)
- **AI 编程代理**: 代码生成和修改
- **OpenAPI 端点**: 完整的 REST API
- **多模型支持**: 支持各种 LLM 提供商
- **项目分析**: 自动理解代码库

## 📡 API 端点

### 🔐 认证访问 (Basic Auth)
```bash
curl -u admin:admin123 http://localhost:7860/opencode/global/health
```

### 🌐 可用端点

#### OpenCode 核心 API
```bash
# 健康检查
curl -u admin:admin123 http://localhost:7860/opencode/global/health

# API 文档 (Swagger)
curl -u admin:admin123 http://localhost:7860/opencode/doc

# 项目管理
curl -u admin:admin123 http://localhost:7860/opencode/project

# 会话管理
curl -u admin:admin123 http://localhost:7860/opencode/session

# 提供商管理
curl -u admin:admin123 http://localhost:7860/opencode/provider
```

#### Nginx 原生端点
```bash
# 主页
curl -u admin:admin123 http://localhost:7860/

# 健康检查
curl -u admin:admin123 http://localhost:7860/health
```

## 🤖 OpenCode 使用示例

### 创建新的编程会话
```bash
# 创建会话
curl -u admin:admin123 -X POST \
  -H "Content-Type: application/json" \
  -d '{"title": "AI Coding Session"}' \
  http://localhost:7860/opencode/session
```

### 发送编程请求
```bash
# 发送 AI 请求
curl -u admin:admin123 -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [
      {"type": "text", "text": "创建一个简单的 Hello World Python 应用"}
    ]
  }' \
  http://localhost:7860/opencode/session/{session_id}/message
```

### 搜索和分析代码
```bash
# 搜索文件
curl -u admin:admin123 \
  "http://localhost:7860/opencode/find/file?query=main.py"

# 读取文件内容
curl -u admin:admin123 \
  "http://localhost:7860/opencode/file/content?path=/path/to/file.py"
```

## 🛡️ 安全特性

### 1. 认证保护
- **Basic Auth**: 用户名/密码保护
- **用户掩码**: 日志中敏感信息已遮蔽
- **会话管理**: 连接复用和清理

### 2. Lua 安全过滤
- **用户代理检测**: 阻止恶意 bot
- **请求验证**: 预防恶意请求
- **日志记录**: 安全事件追踪

### 3. API 安全
- **代理验证**: 只允许 OpenCode API
- **CORS 控制**: 限制跨域访问
- **超时控制**: 防止长时间请求

## 🚀 部署信息

### Docker 配置
```yaml
services:
  opencode-nginx:
    build: .
    ports:
      - "7860:7860"
    environment:
      - GATEWAY_HOST=127.0.0.1
      - GATEWAY_PORT=57860
```

### 访问地址
- **主应用**: http://localhost:7860/
- **OpenCode API**: http://localhost:7860/opencode/
- **API 文档**: http://localhost:7860/opencode/doc
- **健康检查**: http://localhost:7860/health

## 🔧 开发和调试

### 检查服务状态
```bash
# 检查 OpenCode 状态
curl -s http://127.0.0.1:57860/global/health

# 检查 Nginx 状态
curl -u admin:admin123 http://localhost:7860/health

# 查看 Nginx 日志
docker logs [container_name] | grep nginx

# 查看 OpenCode 日志
docker logs [container_name] | grep opencode
```

### 故障排除
1. **认证失败**: 检查用户名/密码 (admin/admin123)
2. **OpenCode 不可达**: 确认内部端口 57860
3. **API 代理失败**: 检查 nginx 配置中的代理设置
4. **CORS 错误**: 确认正确的 Origin 头部设置

## 📊 性能和监控

### 健康检查响应
```json
{
  "healthy": true,
  "version": "1.0.220",
  "service": "OpenResty + OpenCode Integration"
}
```

### 认证头部
```http
X-Powered-By: OpenResty
X-Auth-Type: Basic + Lua
Server: openresty/1.27.1.2
```

## 🎯 使用场景

1. **AI 编程助手**: 通过 API 调用 AI 进行代码生成
2. **自动化开发**: 集成到 CI/CD 流程
3. **代码分析**: 自动理解大型代码库
4. **功能开发**: 快速添加新功能
5. **Bug 修复**: AI 辅助调试和修复

这个集成将强大的 AI 编程能力与安全的企业级 Web 服务器完美结合！