# 🚀 HuggingFace Space 部署指南

## 📋 部署前检查

✅ **所有配置已验证通过**
- Dockerfile 配置正确
- nginx 代理配置完整
- OpenCode 启动脚本就绪
- 认证和安全配置完善
- README.md 元数据正确

## 🎯 部署目标

实现 **API 和 Web 统一端口访问**，让用户能在手机上通过浏览器直接进行 AI 编程交互。

## 📊 架构概览

```
HuggingFace Space (Docker)
├── Nginx (端口 7860)
│   ├── HTTP Basic Auth (admin/admin123)
│   ├── Lua 安全过滤
│   └── 代理到 /opencode/ → OpenCode
└── OpenCode Serve (端口 57860)
    ├── Web 界面 (SPA)
    ├── API 端点 (REST)
    └── API 文档 (Swagger UI)
```

## 🔗 访问端点

### 🌐 Web 界面访问
```
https://[your-space].hf.space/opencode/
```
- 完整的 AI 编程 Web 界面
- 响应式设计，支持移动端
- 实时 AI 对话交互
- 代码编辑和项目管理

### 📡 API 端点访问
```
# API 文档 (Swagger UI)
https://[your-space].hf.space/opencode/doc

# 健康检查
https://[your-space].hf.space/opencode/global/health

# 会话管理
https://[your-space].hf.space/opencode/session

# 其他 API...
https://[your-space].hf.space/opencode/*
```

### 🔐 认证信息
```
用户名: admin
密码: admin123
```

## 📱 移动端使用

### 🎯 手机浏览器访问
1. 打开手机浏览器
2. 访问 `https://[your-space].hf.space/opencode/`
3. 输入认证信息 `admin/admin123`
4. 开始 AI 编程交互

### ✨ 移动端特性
- 📱 响应式界面设计
- 👆 触摸友好的交互
- 💬 实时 AI 对话
- 📝 代码编辑功能
- 📚 集成 API 文档

## 🚀 部署步骤

### 步骤 1: 上传代码到 HuggingFace Space
```bash
git add .
git commit -m "Ready for HuggingFace Space deployment"
git push origin main
```

### 步骤 2: 等待构建完成
- HuggingFace 会自动构建 Docker 镜像
- 预计构建时间：3-5 分钟
- 查看构建日志确认无错误

### 步骤 3: 验证部署
```bash
# 检查服务状态
curl -u admin:admin123 https://[your-space].hf.space/health

# 检查 OpenCode 集成
curl -u admin:admin123 https://[your-space].hf.space/opencode/global/health

# 访问 Web 界面
# 浏览器访问: https://[your-space].hf.space/opencode/
```

## 🧪 功能测试

### ✅ 基础功能测试
- [ ] Web 界面正常加载
- [ ] 认证登录成功
- [ ] AI 对话响应正常
- [ ] API 端点访问正常

### 📱 移动端测试
- [ ] 手机浏览器访问正常
- [ ] 界面响应式适配
- [ ] 触摸操作流畅
- [ ] AI 交互功能完整

### 🔌 API 测试
```bash
# 创建 AI 会话
curl -u admin:admin123 -X POST \
  -H "Content-Type: application/json" \
  -d '{"title": "Mobile Test Session"}' \
  https://[your-space].hf.space/opencode/session

# 发送 AI 请求
curl -u admin:admin123 -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [{"type": "text", "text": "Hello from mobile!"}]
  }' \
  https://[your-space].hf.space/opencode/session/[session_id]/message
```

## 🔧 故障排除

### 常见问题

#### 1. 构建失败
- 检查 Dockerfile 语法
- 确认所有依赖包可用
- 查看构建日志错误信息

#### 2. 认证失败
- 确认用户名密码：`admin/admin123`
- 检查 .htpasswd 文件生成
- 验证 Basic Auth 配置

#### 3. OpenCode 不可达
- 检查内部端口 57860
- 验证 nginx 代理配置
- 确认 OpenCode 启动成功

#### 4. 移动端显示异常
- 检查响应式 CSS
- 验证 viewport 配置
- 测试不同浏览器兼容性

### 📊 监控检查

#### 服务健康状态
```bash
# Nginx 健康检查
curl -u admin:admin123 https://[your-space].hf.space/health

# OpenCode 健康检查
curl -u admin:admin123 https://[your-space].hf.space/opencode/global/health
```

#### 日志查看
```bash
# 在 HuggingFace Space 中查看容器日志
# 检查 nginx 和 opencode 服务状态
```

## 🎉 部署成功！

### 🌟 预期效果
- ✅ **统一访问入口** - 单一端口提供 Web + API
- ✅ **移动端完美支持** - 手机浏览器直接使用
- ✅ **企业级安全** - 认证 + 过滤 + 日志
- ✅ **完整 AI 功能** - 编程 + 对话 + 文档
- ✅ **高性能代理** - Nginx 负载均衡

### 🚀 开始使用
1. **桌面端**: 访问 Web 界面进行完整 AI 编程
2. **移动端**: 手机浏览器随时随地进行 AI 交互
3. **API 集成**: 通过 REST API 集成到其他应用
4. **文档查看**: Swagger UI 提供完整 API 文档

---

**🎯 恭喜！您已成功实现 API 和 Web 统一端口访问，支持移动端 AI 编程交互！**