1 line
17 KiB
JSON
1 line
17 KiB
JSON
{"repo": "alibaba/opc-starter", "files": {"ALIYUN-DEPLOY.md": {"186fa05581a2d8d60e1876b206537f3223b31f9d": {"t": 1785674236.5921626, "n": 11608, "h": "95b83b0ff02b4a73", "c": "# 阿里云部署指南\n\n> OPC-Starter 一人公司启动器 | 阿里云全托管部署方案\n> \n> 适用版本: v1.0+ | 最后更新: 2026-01\n\n---\n\n## 📋 目录\n\n- [架构概览](#架构概览)\n- [先决条件](#先决条件)\n- [快速部署 (3 步完成)](#快速部署-3-步完成)\n- [详细部署步骤](#详细部署步骤)\n - [Step 1: Supabase 数据库](#step-1-supabase-数据库)\n - [Step 2: 百炼 AI API](#step-2-百炼-ai-api)\n - [Step 3: ESA Pages 前端](#step-3-esa-pages-前端)\n- [环境变量配置清单](#环境变量配置清单)\n- [自定义域名配置](#自定义域名配置)\n- [安全最佳实践](#安全最佳实践)\n- [故障排除](#故障排除)\n- [常见问题](#常见问题)\n\n---\n\n## 架构概览\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ 用户浏览器 │\n└─────────────────────────────────────┬───────────────────────────┘\n │ HTTPS\n ▼\n┌─────────────────────────────────────────────────────────────────┐\n│ 阿里云 ESA Pages │\n│ (静态资源托管) │\n│ - React SPA │\n│ - 全球 CDN 加速 │\n└─────────────────────────────────────┬───────────────────────────┘\n │\n ┌─────────────────┴─────────────────┐\n │ │\n ▼ ▼\n┌───────────────────────────────┐ ┌───────────────────────────────┐\n│ Supabase (ADB-PG) │ │ 阿里云百炼 AI │\n│ - PostgreSQL 数据库 │ │ - Qwen-Plus 模型 │\n│ - 用户认证 Auth │ │ - OpenAI SDK 兼容 │\n│ - 文件存储 Storage │ │ - Agent 智能助手 │\n│ - Edge Functions │ │ │\n│ - Realtime 实时同步 │ │ │\n└───────────────────────────────┘ └───────────────────────────────┘\n```\n\n**技术栈版本:**\n| 组件 | 版本 | 说明 |\n|------|------|------|\n| React | 19.1 | 前端框架 |\n| TypeScript | 5.9 | 类型安全 |\n| Vite | 7.1 | 构建工具 |\n| Tailwind CSS | 4.1 | 样式框架 |\n| Supabase | 2.80 | BaaS 后端 |\n| Qwen-Plus | via 百炼 | AI 模型（通义千问） |\n\n---\n\n## 先决条件\n\n### 必需账号\n\n| 服务 | 用途 | 注册链接 |\n|------|------|----------|\n| 阿里云账号 | ESA Pages + 百炼 AI | [注册](https://account.aliyun.com/register/register.htm) |\n| Supabase 账号 | 数据库 + 认证 + 存储 | [注册](https://supabase.com/) |\n\n### 本地环境\n\n```bash\n# 检查 Node.js 版本 (需要 >= 20.x)\nnode -v\n\n# 检查 npm 版本 (需要 >= 10.x) \nnpm -v\n\n# 检查 Git\ngit --version\n```\n\n### 预估费用\n\n| 服务 | 免费额度 | 超出费用 |\n|------|----------|----------|\n| Supabase | 500MB 数据库, 1GB 存储 | $25/月起 |\n| ESA Pages | 100GB 流量/月 | ¥0.24/GB |\n| 百炼 AI | 新用户赠送额度 | 按 Token 计费 |\n\n---\n\n## 快速部署 (3 步完成)\n\n> ⏱️ 预计时间: 15-30 分钟\n\n### Step 1: 配置 Supabase\n\n```bash\n# 1. 访问 Supabase Dashboard 创建项目\n# https://supabase.com/dashboard\n\n# 2. 在 SQL Editor 执行数据库初始化脚本\n# 脚本位置: app/supabase/setup.sql\n\n# 3. 记录以下信息 (Settings → API):\n# - Project URL: https://xxx.supabase.co\n# - anon public key: eyJxxx...\n```\n\n### Step 2: 配置百炼 AI\n\n```bash\n# 1. 访问百炼控制台创建 API Key\n# https://bailian.console.aliyun.com/cn-beijing/?tab=model#/api-key\n\n# 2. 在 Supabase Dashboard 配置 Edge Function Secret:\n# Edge Functions → Secrets → Add new secret\n# Name: ALIYUN_BAILIAN_API_KEY\n# Value: sk-xxx (你的百炼 API Key)\n```\n\n### Step 3: 部署前端\n\n```bash\n# 1. 克隆项目并进入 app 目录\ngit clone https://github.com/your-username/opc-starter.git\ncd opc-starter/app\n\n# 2. 安装依赖\nnpm install\n\n# 3. 配置环境变量\ncp env.local.example .env.local\n# 编辑 .env.local，填入 Supabase URL 和 Key\n\n# 4. 构建项目\nnpm run build\n\n# 5. 安装 ESA CLI 并登录\nnpm i esa-cli@latest -g\nesa-cli login\n\n# 6. 部署到 ESA Pages\nesa-cli deploy\n```\n\n**🎉 部署完成！** 访问 ESA 控制台查看你的站点 URL。\n\n---\n\n## 详细部署步骤\n\n### Step 1: Supabase 数据库\n\n#### 1.1 创建 Supabase 项目\n\n1. 登录 [Supabase Dashboard](https://supabase.com/dashboard)\n2. 点击 **New Project**\n3. 填写项目信息:\n - **Name**: `opc-starter-prod` (自定义名称)\n - **Database Password**: 设置强密码并妥善保存\n - **Region**: 选择最近的区域 (如 Southeast Asia - Singapore)\n4. 等待项目创建完成 (约 2 分钟)\n\n#### 1.2 初始化数据库 Schema\n\n1. 进入 **SQL Editor**\n2. 点击 **New query**\n3. 复制粘贴 `app/supabase/setup.sql` 的全部内容\n4. 点击 **Run** 执行\n\n> 💡 **提示**: 脚本会创建 `profiles`, `organizations`, `organization_members`, `agent_*` 等表，并配置 RLS 安全策略。\n\n#### 1.3 配置 Storage Bucket\n\n1. 进入 **Storage**\n2. 点击 **Create a new bucket**\n3. 创建以下 Bucket:\n\n| Bucket 名称 | 公开访问 | 用途 |\n|-------------|----------|------|\n| `avatars` | ✅ Public | 用户头像 |\n| `uploads` | ❌ Private | 用户上传文件 |\n\n#### 1.4 获取项目凭证\n\n进入 **Settings → API**，记录以下信息:\n\n```yaml\n# 保存到安全位置\nSUPABASE_URL: https://xxxxx.supabase.co\nSUPABASE_ANON_KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\nSUPABASE_SERVICE_ROLE_KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... # 仅后端使用\n```\n\n#### 1.5 部署 Edge Functions\n\n```bash\n# 在 app 目录下\ncd app\n\n# 登录 Supabase CLI\nnpx supabase login\n\n# 链接到你的项目\nnpx supabase link --project-ref <your-project-ref>\n\n# 部署 AI Assistant Function\nnpx supabase functions deploy ai-assistant\n\n# 配置 Secrets (下一步获取百炼 API Key 后执行)\nnpx supabase secrets set ALIYUN_BAILIAN_API_KEY=sk-xxx\n```\n\n---\n\n### Step 2: 百炼 AI API\n\n#### 2.1 开通百炼服务\n\n1. 访问 [阿里云百炼控制台](https://bailian.console.aliyun.com/)\n2. 如未开通，点击 **开通服务** (按量付费)\n3. 完成实名认证 (如需)\n\n#### 2.2 创建 API Key\n\n1. 进入 **API-KEY 管理**: [直达链接](https://bailian.console.aliyun.com/cn-beijing/?tab=model#/api-key)\n2. 点击 **创建新的 API-KEY**\n3. 设置名称: `opc-starter-prod`\n4. 复制生成的 Key (格式: `sk-xxx`)\n\n> ⚠️ **安全提醒**: API Key 只显示一次，请立即保存到安全位置。\n\n#### 2.3 配置到 Supabase Edge Functions\n\n**方式一: 通过 Dashboard (推荐新手)**\n\n1. Supabase Dashboard → **Edge Functions**\n2. 点击 **Secrets** 标签\n3. **Add new secret**:\n - Name: `ALIYUN_BAILIAN_API_KEY`\n - Value: `sk-xxx` (你的百炼 API Key)\n\n**方式二: 通过 CLI**\n\n```bash\nnpx supabase secrets set ALIYUN_BAILIAN_API_KEY=sk-xxx\n```\n\n#### 2.4 验证配置\n\n```bash\n# 测试 Edge Function\ncurl -X POST 'https://YOUR_PROJECT_REF.supabase.co/functions/v1/ai-assistant' \\\n -H 'Authorization: Bearer YOUR_ANON_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"messages\":[{\"role\":\"user\",\"content\":\"你好\"}]}'\n```\n\n---\n\n### Step 3: ESA Pages 前端\n\n#### 3.1 安装 ESA CLI\n\n```bash\n# 全局安装 ESA CLI\nnpm install esa-cli@latest -g\n\n# 验证安装\nesa-cli --version\n```\n\n#### 3.2 配置阿里云访问凭证\n\n```bash\n# 登录 (需要阿里云 AccessKey)\nesa-cli login\n```\n\n**获取 AccessKey:**\n\n1. 访问 [AccessKey 管理](https://ram.console.aliyun.com/manage/ak)\n2. 创建 AccessKey (建议使用 RAM 子账号)\n3. 记录 AccessKey ID 和 AccessKey Secret\n\n> ⚠️ **安全提醒**: \n> - 不要使用主账号 AccessKey\n> - 建议创建专用 RAM 用户并仅授予 ESA 权限\n> - 设置 AccessKey 轮转策略\n\n#### 3.3 配置前端环境变量\n\n```bash\ncd app\n\n# 复制环境变量模板\ncp env.local.example .env.local\n\n# 编辑配置\nnano .env.local # 或使用你喜欢的编辑器\n```\n\n**`.env.local` 配置内容:**\n\n```bash\n# Supabase 配置 (必需)\nVITE_SUPABASE_URL=https://xxxxx.supabase.co\nVITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...\n\n# 开发调试 (可选)\nVITE_ENABLE_MSW=false\nVITE_LOG_LEVEL=info\n```\n\n#### 3.4 构建项目\n\n```bash\n# 安装依赖 (如未安装)\nnpm install\n\n# 构建生产版本\nnpm run build\n\n# 本地预览 (可选)\nnpm run preview\n```\n\n#### 3.5 部署到 ESA Pages\n\n**查看部署配置:**\n\n```bash\ncat esa.jsonc\n```\n\n```json\n{\n \"name\": \"opc-starter\",\n \"assets\": {\n \"directory\": \"./dist\",\n \"notFoundStrategy\": \"singlePageApplication\"\n }\n}\n```\n\n**执行部署:**\n\n```bash\nesa-cli deploy\n```\n\n**部署成功输出示例:**\n\n```\n✔ Deployment successful!\n Site URL: https://opc-starter.esa.aliyun.com\n Deploy ID: deploy_xxxxx\n```\n\n---\n\n## 环境变量配置清单\n\n### 前端环境变量 (`.env.local`)\n\n| 变量名 | 必需 | 说明 | 示例值 |\n|--------|------|------|--------|\n| `VITE_SUPABASE_URL` | ✅ | Supabase 项目 URL | `https://xxx.supabase.co` |\n| `VITE_SUPABASE_ANON_KEY` | ✅ | Supabase 匿名 Key | `eyJxxx...` |\n| `VITE_ENABLE_MSW` | ❌ | 启用 Mock (仅开发) | `false` |\n| `VITE_LOG_LEVEL` | ❌ | 日志级别 | `info` |\n\n### Edge Function Secrets\n\n| Secret 名称 | 必需 | 说明 | 获取方式 |\n|-------------|------|------|----------|\n| `ALIYUN_BAILIAN_API_KEY` | ✅ | 百炼 AI API Key | [百炼控制台](https://bailian.console.aliyun.com/cn-beijing/?tab=model#/api-key) |\n| `SUPABASE_URL` | 🔄 | 自动注入 | - |\n| `SUPABASE_ANON_KEY` | 🔄 | 自动注入 | - |\n| `SUPABASE_SERVICE_ROLE_KEY` | 🔄 | 自动注入 | - |\n\n> 🔄 = Supabase 自动注入，无需手动配置\n\n---\n\n## 自定义域名配置\n\n### 前提条件\n\n- 已完成域名备案 (中国大陆访问必需)\n- 域名 DNS 托管或可修改 DNS 记录\n\n### 配置步骤\n\n1. **获取 ESA Pages 默认域名**\n \n 部署成功后会分配一个 `xxx.esa.aliyun.com` 域名\n\n2. **添加自定义域名**\n \n - 访问 [ESA 控制台](https://esa.console.aliyun.com/)\n - 进入你的站点 → **域名管理**\n - 点击 **添加域名**\n - 输入你的域名 (如 `app.yourdomain.com`)\n\n3. **配置 DNS 解析**\n \n 添加 CNAME 记录指向 ESA 提供的地址:\n \n | 主机记录 | 记录类型 | 记录值 |\n |----------|----------|--------|\n | `app` | CNAME | `xxx.esa.aliyun.com` |\n\n4. **配置 HTTPS 证书**\n \n ESA 支持自动申请免费证书，或上传自有证书\n\n5. **更新 Supabase 配置**\n \n 如果使用自定义域名，记得在 Supabase Dashboard 中:\n - **Authentication → URL Configuration** 更新 Site URL\n - **Authentication → Redirect URLs** 添加新域名\n\n---\n\n## 安全最佳实践\n\n### 1. Supabase MCP 安全\n\n```yaml\n# 推荐配置\n- 开启 Read-Only 模式 (除非必要)\n- 启用 RLS (Row Level Security) - 默认已启用\n- 定期审计 RLS 策略\n```\n\n### 2. 百炼 API Key 安全\n\n```yaml\n# 推荐配置\n- 为不同环境创建不同的 API Key\n- 设置 API Key 调用限额\n- 定期轮转 Key (建议每 90 天)\n- 监控异常调用量\n```\n\n### 3. 阿里云 AccessKey 安全\n\n```yaml\n# 强烈推荐\n- ❌ 不要使用主账号 AccessKey\n- ✅ 创建 RAM 子账号\n- ✅ 仅授予必要权限 (最小权限原则)\n- ✅ 设置 AccessKey 轮转策略\n- ✅ 启用 MFA 多因素认证\n```\n\n**创建专用 RAM 用户:**\n\n```bash\n# RAM 策略示例 - 仅 ESA Pages 权限\n{\n \"Version\": \"1\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": \"esa:*\",\n \"Resource\": \"*\"\n }\n ]\n}\n```\n\n### 4. 生产环境检查清单\n\n- [ ] 关闭前端 MSW Mock (`VITE_ENABLE_MSW=false`)\n- [ ] 设置适当的日志级别 (`VITE_LOG_LEVEL=info` 或 `warn`)\n- [ ] 确认 Supabase RLS 策略正确配置\n- [ ] 确认 Edge Function Secrets 已配置\n- [ ] 配置 HTTPS (ESA 默认支持)\n- [ ] 设置 CORS 策略 (Edge Function 已配置)\n\n---\n\n## 故障排除\n\n### 问题 1: ESA 部署失败\n\n**症状:** `esa-cli deploy` 报错\n\n**排查步骤:**\n\n```bash\n# 1. 检查登录状态\nesa-cli whoami\n\n# 2. 重新登录\nesa-cli login\n\n# 3. 检查构建产物\nls -la dist/\n\n# 4. 验证 esa.jsonc 配置\ncat esa.jsonc\n```\n\n### 问题 2: AI 助手无响应\n\n**症状:** Agent 对话无回复或报错\n\n**排查步骤:**\n\n```bash\n# 1. 检查 Edge Function 日志\nnpx supabase functions logs ai-assistant\n\n# 2. 验证 Secret 配置\nnpx supabase secrets list\n\n# 3. 测试百炼 API 连通性\ncurl -X POST 'https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions' \\\n -H 'Authorization: Bearer sk-xxx' \\\n -H 'Content-Type: application/json' \\\n -d '{\"model\":\"qwen-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"test\"}]}'\n```\n\n### 问题 3: 登录/认证失败\n\n**症状:** 无法登录或 Session 丢失\n\n**排查步骤:**\n\n1. 检查 `VITE_SUPABASE_URL` 和 `VITE_SUPABASE_ANON_KEY` 是否正确\n2. 确认 Supabase Dashboard → Authentication → URL Configuration 设置正确\n3. 检查浏览器控制台是否有 CORS 错误\n\n### 问题 4: 数据库连接错误\n\n**症状:** 页面显示 \"Failed to fetch\" 或类似错误\n\n**排查步骤:**\n\n1. 确认 Supabase 项目状态为 Active\n2. 检查 RLS 策略是否正确配置\n3. 验证 Anon Key 是否匹配当前项目\n\n---\n\n## 常见问题\n\n### Q1: Supabase 免费额度够用吗？\n\n**A:** 对于个人项目或小团队，免费额度 (500MB 数据库, 1GB 存储, 50K MAU) 通常足够。建议在 Dashboard 中设置用量告警。\n\n### Q2: 百炼 AI 有哪些模型可用？\n\n**A:** 本项目默认使用 `qwen-plus`。百炼支持的通义千问模型包括:\n- Qwen-Plus (推荐，长上下文 1M tokens，性价比高)\n- Qwen-Max (最强能力，上下文 256K tokens)\n- Qwen-Turbo (快速响应，中等复杂度)\n\n可在 `ai-assistant/index.ts` 中修改模型配置。\n\n### Q3: 如何切换到其他 LLM 提供商？\n\n**A:** Edge Function 使用 OpenAI SDK 兼容模式，可轻松切换:\n\n```typescript\n// 切换到 OpenAI\nconst openai = new OpenAI({\n apiKey: Deno.env.get('OPENAI_API_KEY'),\n // 移除 baseURL 使用默认 OpenAI 地址\n})\n\n// 或切换到其他兼容服务\nconst openai = new OpenAI({\n apiKey: Deno.env.get('OTHER_API_KEY'),\n baseURL: 'https://other-provider.com/v1',\n})\n```\n\n### Q4: ESA Pages 支持哪些区域？\n\n**A:** ESA Pages 支持全球部署，自动通过阿里云 CDN 加速。中国大陆访问需要域名备案。\n\n### Q5: 如何查看部署日志？\n\n**A:** \n- **ESA Pages**: ESA 控制台 → 站点详情 → 部署记录\n- **Edge Functions**: `npx supabase functions logs <function-name>`\n- **前端错误**: 浏览器开发者工具 Console\n\n### Q6: 支持私有化部署吗？\n\n**A:** 本项目设计为云托管部署。如需私有化:\n- Supabase 可自托管 (Self-hosted Supabase)\n- 前端可部署到任意静态托管服务\n- AI 服务可替换为私有部署的模型\n\n---\n\n## 获取帮助\n\n- 📖 [项目文档](./docs/)\n- 🐛 [提交 Issue](https://github.com/your-username/opc-starter/issues)\n- 💬 [讨论区](https://github.com/your-username/opc-starter/discussions)\n\n---\n\n<p align=\"center\">\n <sub>Made with ❤️ for Solo Entrepreneurs</sub>\n</p>\n"}}}} |