OPENCODE_INTEGRATION.md

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)

curl -u admin:admin123 http://localhost:7860/opencode/global/health

🌐 可用端点

OpenCode 核心 API

# 健康检查
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 原生端点

# 主页
curl -u admin:admin123 http://localhost:7860/

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

🤖 OpenCode 使用示例

创建新的编程会话

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

发送编程请求

# 发送 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

搜索和分析代码

# 搜索文件
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 配置

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

🔧 开发和调试

检查服务状态

# 检查 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 头部设置

📊 性能和监控

健康检查响应

{
  "healthy": true,
  "version": "1.0.220",
  "service": "OpenResty + OpenCode Integration"
}

认证头部

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 服务器完美结合！