# Python 微服?SAE 部署操作手册 **文档版本**: v1.0 **创建时间**: 2024-12-24 **适用范围**: AI临床研究平台 - Python微服务（extraction_service? **环境类型**: 测试环境（轻量版SAE? **目标读?*: 运维工程师、开发工程师 --- ## 📋 目录 1. [前置检查清单](#前置检查清? 2. [创建SAE应用（Web控制台）](#创建sae应用web控制? 3. [部署后验证](#部署后验? 4. [集成配置](#集成配置) 5. [常见问题排查](#常见问题排查) --- ## 前置检查清? ### ?必需资源确认 在开始创建SAE应用前，请确认以下资源已准备就绪? | 资源类型 | 确认?| 获取位置 | |---------|-------|---------| | **Docker镜像** | ?已推送至ACR | [部署进度总览.md - 2.1 ACR容器镜像仓库](./00-部署进度总览.md#21-acr容器镜像仓库) | | **VPC网络** | ?VPC ID、vSwitch ID | [部署进度总览.md - 2.2 VPC网络](./00-部署进度总览.md#22-vpc网络与nat网关) | | **安全?* | ?安全组ID | [部署进度总览.md - 2.2 VPC网络](./00-部署进度总览.md#22-vpc网络与nat网关) | | **OSS存储** | ?AccessKey、Bucket名称 | [部署进度总览.md - 2.5 OSS对象存储](./00-部署进度总览.md#25-oss对象存储) | | **SAE命名空间** | ?命名空间ID | [部署进度总览.md - 2.4 SAE应用](./00-部署进度总览.md#24-sae-serverless应用) | ### 📦 镜像信息 ``` 镜像地址（VPC内网）： crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.0 镜像版本：v1.0 镜像大小?.12GB 功能说明：PDF/Docx提取 + 数据清洗（pandas/polars?``` ### 🌐 网络配置信息 ``` VPC ID：vpc-2ze055cptkew9c38w4r06 vSwitch ID：vsw-2zevacop039bxrmj6yc0c（可用区F?安全组ID：sg-2zedk6fi8sgmmcwdu7tu 命名空间：cn-beijing:test-airesearch ``` ### 🗄?OSS配置信息 ``` OSS_ACCESS_KEY_ID：LTAI5tB2Dt3NdvBL3G7nYGv7 OSS_ACCESS_KEY_SECRET?iSN9k39RkApP93QjUhC1DcPIeMG4V OSS_BUCKET：ai-clinical-research OSS_ENDPOINT：oss-cn-beijing-internal.aliyuncs.com ``` ⚠️ **安全警告**：AccessKey是敏感信息，仅在SAE环境变量中配置，不要提交到Git或打印到日志? --- ## 创建SAE应用（Web控制台） ### 步骤 1：进入SAE控制? 1. 登录 [阿里云控制台](https://homenew.console.aliyun.com/) 2. 搜索并进?**Serverless 应用引擎 SAE** 3. 确认地域?**华北2（北京）** 4. 选择命名空间 **test-airesearch** --- ### 步骤 2：创建应? #### 2.1 基本信息配置 点击 **创建应用** 按钮，填写以下信息： | 配置?| ?| 说明 | |--------|---|------| | **应用名称** | `python-extraction-test` | 建议?`-test` 后缀区分测试环境 | | **应用类型** | **轻量版应?* | 测试环境使用轻量版，节省成本 | | **部署方式** | **镜像** | 选择容器镜像部署 | 点击 **下一?* --- #### 2.2 应用部署配置 ##### 镜像配置 | 配置?| ?| 说明 | |--------|---|------| | **镜像来源** | 容器镜像服务 ACR（或选择"自定义镜??| | | **镜像地址** | `crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.0` | ⚠️ 必须使用VPC内网地址
⚠️ 必须包含版本?`:v1.0` | | **镜像版本** | `v1.0` | 固定版本号，不要使用 `:latest`
⚠️ 如果不指定版本号，SAE会默认使?`:latest` 导致拉取失败 | | **镜像仓库认证** | **需要配?* | ⚠️ **关键步骤**：配置ACR访问凭证（见下方?| ##### 🔑 镜像仓库认证配置（关键步骤） **⚠️ 如果出现 `insufficient_scope: authorization failed` 错误，必须配置此?* 找到 **"镜像仓库认证"** ?**"私有镜像仓库"** 配置项： | 配置?| ?| 说明 | |--------|---|------| | **镜像仓库地址** | `crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com` | 只填写Registry域名，不包含命名空间/仓库?| | **用户?* | `gofeng117@163.com` | ACR登录用户?| | **密码** | `fengzhibo117` | ACR登录密码 | 💡 **说明**?- 这些凭证用于SAE拉取私有镜像 - 密码会被SAE加密存储，不会泄?- 凭证来源：[部署进度总览 - 2.1 ACR容器镜像仓库](./00-部署进度总览.md#21-acr容器镜像仓库) ##### 应用实例配置 | 配置?| ?| 说明 | |--------|---|------| | **CPU** | 1?| `1000 millicores` | | **内存** | 2GB | `2048 MB` | | **实例?* | 1 | ⚠️ 必须至少1个实例，0个实?服务停止 | ##### 应用访问设置 | 配置?| ?| 说明 | |--------|---|------| | **容器端口** | `8000` | Python FastAPI服务端口 | | **协议类型** | HTTP | | | **是否开启公网访?* | **?* | 仅内网访问，被Node.js后端调用 | 点击 **下一?* --- #### 2.3 环境配置 ##### 环境变量 点击 **添加环境变量**，逐个添加以下配置? | 变量?| 变量?| 说明 | |--------|--------|------| | `LOG_LEVEL` | `INFO` | 日志级别 | | `TEMP_DIR` | `/tmp/extraction_service` | 临时文件目录 | | `TZ` | `Asia/Shanghai` | 时区设置 | | `SERVICE_NAME` | `python-extraction` | 服务标识 | | `SERVICE_VERSION` | `v1.0` | 版本标识 | | `OSS_ACCESS_KEY_ID` | `LTAI5tB2Dt3NdvBL3G7nYGv7` | OSS访问密钥ID | | `OSS_ACCESS_KEY_SECRET` | `1iSN9k39RkApP93QjUhC1DcPIeMG4V` | OSS访问密钥Secret | | `OSS_BUCKET` | `ai-clinical-research` | OSS Bucket名称 | | `OSS_ENDPOINT` | `oss-cn-beijing-internal.aliyuncs.com` | OSS内网Endpoint | ⚠️ **注意**?- 环境变量中的 `OSS_ACCESS_KEY_SECRET` 是敏感信息，SAE会自动加?- 所有环境变量都可以在应用部署后修改 ##### 健康检? | 配置?| ?| 说明 | |--------|---|------| | **健康检查方?* | HTTP | | | **健康检查路?* | `/api/health` | FastAPI健康检查端?| | **健康检查端?* | `8000` | | | **初始延迟时间** | `40` ?| 给镜像拉取和服务启动留时?| | **检查间?* | `30` ?| | | **检查超?* | `10` ?| | | **健康阈?* | `2` ?| 连续2次成功视为健?| | **不健康阈?* | `3` ?| 连续3次失败视为不健康 | 点击 **下一?* --- #### 2.4 网络配置 | 配置?| ?| 说明 | |--------|---|------| | **专有网络VPC** | `vpc-2ze055cptkew9c38w4r06` | ai-clinical-vpc | | **虚拟交换机vSwitch** | `vsw-2zevacop039bxrmj6yc0c` | 可用区F | | **安全?* | `sg-2zedk6fi8sgmmcwdu7tu` | | | **SLB公网访问** | **不配?* | 仅内网访?| 点击 **下一?* --- #### 2.5 应用生命周期配置（可选，使用默认即可? | 配置?| 默认?| 说明 | |--------|--------|------| | **启动超时时间** | 300?| 镜像较大，需要较长启动时?| | **优雅停机超时** | 30?| 给应用处理完当前请求的时?| 点击 **下一?* --- #### 2.6 确认配置 1. 仔细检查所有配置项是否正确 2. 特别确认? - ?镜像地址使用VPC内网地址 - ?实例?= 1（不?? - ?OSS环境变量已配? - ?健康检查路径为 `/api/health` 3. 点击 **创建应用** --- ### 步骤 3：等待部署完? 部署过程大约需?**3-5分钟**，SAE会自动执行以下步骤： ``` 1. 拉取Docker镜像（约2-3分钟，镜?.12GB? └─ 使用VPC内网，速度较快 2. 启动容器（约30秒） └─ 执行Dockerfile中的CMD命令 3. 健康检查（?-2分钟? └─ 等待40秒后开始检?/api/health 4. 应用运行中（部署成功? └─ 实例状态变?运行? ``` **实时监控部署进度**?- SAE控制??应用详情 ?变更记录 ?查看详情 **查看部署日志**?- SAE控制??应用详情 ?日志查询 ?实时日志 **预期日志内容**?```log INFO: Started server process [1] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit) ``` --- ## 部署后验? ### 步骤 1：获取内网访问地址 **⚠️ 关键步骤：必须从SAE控制台获取真实内网IP** #### 获取方法? 1. SAE控制??应用列表 ?点击 `python-extraction-test` 2. 进入应用详情?3. 找到 **实例列表** ?**基本信息** 4. 查看 **内网IP地址** **预期格式**?``` 内网IP?72.17.x.x 端口?000 完整地址：http://172.17.x.x:8000 ``` **⚠️ 重要**?- ?不要猜测域名（如 `extraction-service.internal`?- ?不要使用 `localhost:8000` - ?必须使用SAE控制台显示的真实IP地址 **记录内网地址**?``` # ?已获取内网地址?024-12-24）： PYTHON_SERVICE_INTERNAL_IP=172.17.173.66:8000 PYTHON_SERVICE_URL=http://172.17.173.66:8000 ``` ⚠️ **重要提醒**?- 此地址仅在VPC内网可访?- Node.js后端需要配置此地址作为环境变量 - 如果实例重启，IP地址可能会变化（需重新获取? --- ### 步骤 2：健康检查测? #### 方法 1：从SAE控制台测试（推荐? 1. SAE控制??应用详情 ?实例列表 2. 点击实例?**Webshell** 按钮（如果支持） 3. 执行命令（使用Python测试，因为容器中没有curl）： ```bash python -c "import urllib.request; print(urllib.request.urlopen('http://localhost:8000/api/health').read().decode())" ``` ⚠️ **注意**：如果遇?`curl: command not found`，说明容器中没有安装curl工具（精简镜像），请使用上面的Python命令? #### 方法 2：从本地测试（需要临时配置） ⚠️ **注意**：由于Python服务仅在VPC内网，本地无法直接访问，需要以下任一方法? **选项A：通过Node.js后端转发（推荐）** - 待Node.js后端部署后，通过后端间接测试 **选项B：临时配置公网SLB（测试完成后删除?* 1. SAE控制??应用详情 ?应用访问设置 2. 点击 **绑定SLB** 3. 创建或选择公网SLB 4. 测试完成后立即删除SLB **预期响应**?```json { "status": "healthy", "checks": { "pymupdf": { "available": true, "version": "1.26.7" }, "nougat": { "available": false, "error": "Nougat未安装（已移除以减小镜像? }, "temp_dir": { "path": "/tmp/extraction_service", "writable": true } }, "timestamp": "2024-12-24T10:30:00Z" } ``` --- ### 步骤 3：查看应用日? 1. SAE控制??应用详情 ?日志查询 2. 选择 **实时日志** 3. 确认日志中包含： ```log ?正常启动标志?INFO: Started server process [1] INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000 ?健康检查日志（?0秒一次）?INFO: 172.17.x.x:xxxx - "GET /api/health HTTP/1.1" 200 OK ?如果出现错误?ERROR: ImportError: libXXX.so: cannot open shared object file ?说明系统依赖缺失，检查Dockerfile ``` --- ### 步骤 4：监控应用状? SAE控制??应用详情 ?基本信息 **关键指标**?| 指标 | 正常?| 说明 | |------|--------|------| | **应用状?* | 运行?| 绿色 | | **实例?* | 1/1 | 1个实例运行中 | | **健康实例?* | 1 | 健康检查通过 | | **CPU使用?* | < 20% | 空闲状?| | **内存使用?* | < 50% | ?GB（Python基础+依赖?| --- ## 集成配置 ### 步骤 1：更新Node.js后端环境变量 在Node.js后端的SAE应用中，添加以下环境变量? ```bash # Python微服务内网地址 EXTRACTION_SERVICE_URL=http://172.17.x.x:8000 # 注意?# 1. 替换为实际获取的内网IP # 2. 不要加尾部斜?/ ``` **配置位置**?- SAE控制??Node.js后端应用 ?应用配置 ?环境变量 ?添加 **配置后操?*?- 重启Node.js后端应用（SAE会自动重启） --- ### 步骤 2：后端代码验证（可选） 在Node.js后端代码中添加测试端点： ```typescript // backend/src/routes/test.ts import { Router } from 'express'; import axios from 'axios'; const router = Router(); router.get('/test-python-service', async (req, res) => { try { const extractionServiceUrl = process.env.EXTRACTION_SERVICE_URL || 'http://localhost:8000'; // 1. 测试健康检? const healthRes = await axios.get(`${extractionServiceUrl}/api/health`); res.json({ success: true, message: 'Python service is healthy', data: healthRes.data }); } catch (error) { res.status(500).json({ success: false, message: 'Failed to connect to Python service', error: error.message }); } }); export default router; ``` **测试方法**?```bash # 从前端或Postman访问 GET https://your-backend-domain.com/api/test-python-service # 预期响应?{ "success": true, "message": "Python service is healthy", "data": { "status": "healthy", ... } } ``` --- ### 步骤 3：端到端功能测试 测试完整业务流程? #### 测试场景 1：PDF文本提取 **流程**?``` 前端上传PDF ?Node.js后端接收 ?HTTP POST 转发?Python服务 (EXTRACTION_SERVICE_URL) ?Python服务提取文本 ?返回JSON结果 ?后端处理并返回前?``` **测试步骤**?1. 在前端上传一个小的PDF文件? 5MB?2. 查看Node.js后端日志? ```log INFO: Calling Python service: http://172.17.x.x:8000/api/extract/pdf INFO: Python service responded in 2.3s ``` 3. 查看Python服务日志? ```log INFO: Request: POST /api/extract/pdf INFO: File size: 1.2MB, filename: test.pdf INFO: Using PyMuPDF extraction INFO: Response: 200 (took 2.10s) ``` #### 测试场景 2：数据清洗（DC工具? **流程**?``` 前端上传Excel ?后端调用 Python服务 /api/operations/fillna ?Python使用pandas/polars处理 ?返回清洗后的数据 ``` **测试步骤**?1. 在DC模块上传Excel文件 2. 执行数据清洗操作（如fillna?3. 验证返回结果是否正确 --- ## 常见问题排查 ### 问题 1：镜像拉取失败（insufficient_scope: authorization failed? **症状**?``` Error: ImagePullBackOff Failed to pull image: insufficient_scope: authorization failed pull access denied, repository does not exist or may require authorization ``` **根本原因**：SAE没有权限访问ACR私有镜像仓库 **解决步骤**? **方法1：配置镜像仓库认证（推荐?* 1. SAE控制??应用详情 ?点击"部署应用"?编辑应用" 2. ?**"镜像配置"** 部分，找?**"镜像仓库认证"** ?**"私有镜像仓库"** 3. 配置以下信息? ``` 镜像仓库地址：crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com 用户名：gofeng117@163.com 密码：fengzhibo117 ``` 4. 保存配置并重新部? **方法2：使用RAM角色授权（生产环境推荐）** 1. RAM控制??创建角色 ?选择"阿里云服? ?受信服务?SAE" 2. 为角色添加权限：`AliyunContainerRegistryReadOnlyAccess` 3. SAE应用配置 ?高级设置 ?绑定RAM角色 **方法3：设置ACR仓库为公开（仅测试环境?* ⚠️ 不推荐生产环境使用（安全风险? 1. ACR控制??个人实例 ?仓库列表 2. 找到 `ai-clinical/python-extraction` 3. 仓库设置 ?访问控制 ?改为"公开" --- ### 问题 2：应用启动失败（其他原因? **症状**?``` SAE控制台显示：应用启动失败 实例状态：异常 ``` **排查步骤**? **1. 查看部署日志** ``` SAE控制??应用详情 ?变更记录 ?查看详情 ``` **2. 常见错误及解决方?*? | 错误信息 | 原因 | 解决方法 | |---------|------|---------| | `ImagePullBackOff` + `failed to resolve reference "...:latest"` | **镜像地址未指定版本号** | **在镜像地址末尾添加 `:v1.0`**
完整地址：`...python-extraction:v1.0` | | `ImagePullBackOff` + `insufficient_scope: authorization failed` | **ACR访问权限不足（最常见?* | **配置镜像仓库认证**
1. SAE应用配置 ?镜像配置
2. 配置镜像仓库认证
3. 用户名：`gofeng117@163.com`
4. 密码：`fengzhibo117` | | `ImagePullBackOff` + `pull access denied` | 镜像仓库认证失败 | 检查用户名/密码是否正确 | | `ImagePullBackOff` | 镜像地址错误 | 确认使用VPC内网地址（带-vpc后缀?| | `ImportError: libXXX.so` | 系统依赖缺失 | 检查Dockerfile，确保安装了所有运行时依赖 | | `OOMKilled` | 内存不足 | 增加内存配置?GB ?4GB?| | `Health check failed` | 健康检查未通过 | 检?`/api/health` 端点是否正常 | **3. 查看容器日志** ``` SAE控制??应用详情 ?日志查询 ?实时日志 ``` --- ### 问题 3：健康检查失? **症状**?``` 实例列表显示：健康检查失?实例反复重启 ``` **排查步骤**? **1. 确认服务是否正常启动** ```bash # 查看日志中是否有?INFO: Uvicorn running on http://0.0.0.0:8000 ``` **2. 确认端口是否正确** ```bash # 检查容器端口配置：8000 # 检查健康检查端口配置：8000 ``` **3. 手动测试健康检查端?* ```bash # 在SAE Webshell中执行： curl http://localhost:8000/api/health ``` **4. 调整健康检查参?* ``` 初始延迟时间?0??60秒（如果镜像拉取慢） 检查超时：10??20?``` --- ### 问题 4：Node.js后端无法连接Python服务 **症状**?``` 后端日志：Connection refused ?ECONNREFUSED: connect ECONNREFUSED 172.17.x.x:8000 ``` **排查步骤**? **1. 确认内网地址是否正确** ```bash # ?错误配置（猜测的域名?EXTRACTION_SERVICE_URL=http://python-extraction.internal:8000 # ?正确配置（SAE控制台显示的真实IP?EXTRACTION_SERVICE_URL=http://172.17.10.5:8000 ``` **2. 确认Python服务是否运行** ``` SAE控制??Python应用 ?实例列表 状态：运行??``` **3. 确认安全组规?* ``` SAE控制??Python应用 ?网络配置 ?安全?入站规则：允许VPC内访?8000端口 ``` **4. 测试内网连通?* ```bash # 在Node.js后端容器中执行（通过SAE Webshell）： curl http://172.17.x.x:8000/api/health ``` --- ### 问题 5：PDF提取超时 **症状**?``` 后端日志：Request timeout after 300s Python日志：Processing large PDF... ``` **原因**?- 文件过大? 50MB?- PDF包含大量图片 **解决方法**? **1. 增加超时时间** ```bash # Node.js后端环境变量 EXTRACTION_TIMEOUT=600 # 10分钟 ``` **2. 限制文件大小** ```python # Python服务：main.py MAX_FILE_SIZE = 50 * 1024 * 1024 # 50MB @app.post("/api/extract/pdf") async def extract_pdf(file: UploadFile): if file.size > MAX_FILE_SIZE: raise HTTPException(status_code=413, detail="File too large") ``` **3. 优化提取逻辑** ```python # 跳过图片页、压缩图片等 ``` --- ### 问题 6：内存溢出（OOM? **症状**?``` 容器自动重启 日志显示：Killed (signal 9) 实例监控：内存使用率 > 95% ``` **解决方法**? **1. 增加内存配置** ``` SAE控制??应用配置 ?规格 内存?GB ?4GB ``` **2. 优化代码（流式处理）** ```python # 不要一次性加载整个文件到内存 with open(pdf_path, 'rb') as f: for chunk in read_in_chunks(f): process(chunk) ``` **3. 限制并发请求** ```python # main.py from fastapi import FastAPI from starlette.middleware.base import BaseHTTPMiddleware app = FastAPI() # 限制并发连接?app.add_middleware(ConnectionLimitMiddleware, max_connections=10) ``` --- ## 附录 ### A. 快速命令参? **查看应用信息**?```bash # 阿里云CLI aliyun sae DescribeApplicationStatus --AppId ``` **查看实例列表**?```bash # 阿里云CLI aliyun sae DescribeApplicationInstances --AppId ``` **重启应用**?``` SAE控制??应用详情 ?重启应用 ``` **查看实时日志**?``` SAE控制??应用详情 ?日志查询 ?实时日志 ``` --- ### B. 环境变量配置清单 | 变量?| 必需 | 默认?| 说明 | |--------|-----|--------|------| | `LOG_LEVEL` | ?| `INFO` | 日志级别（DEBUG/INFO/WARNING/ERROR?| | `TEMP_DIR` | ?| `/tmp/extraction_service` | 临时文件目录 | | `TZ` | ?| `UTC` | 时区（建?`Asia/Shanghai`?| | `SERVICE_NAME` | ?| - | 服务名称（用于日志标识） | | `SERVICE_VERSION` | ?| - | 服务版本（用于日志标识） | | `OSS_ACCESS_KEY_ID` | ?| - | OSS访问密钥ID | | `OSS_ACCESS_KEY_SECRET` | ?| - | OSS访问密钥Secret | | `OSS_BUCKET` | ?| - | OSS Bucket名称 | | `OSS_ENDPOINT` | ?| - | OSS Endpoint（建议内网） | --- ### C. 部署检查清? **部署?*?- [ ] 确认Docker镜像已推送至ACR - [ ] 确认VPC、vSwitch、安全组ID - [ ] 确认OSS AccessKey有效 - [ ] 确认SAE命名空间已创? **部署?*?- [ ] 镜像地址使用VPC内网地址 - [ ] 实例?= 1（不??- [ ] 容器端口 = 8000 - [ ] 健康检查路?= `/api/health` - [ ] 环境变量配置完整 **部署?*?- [ ] 应用状?= 运行?- [ ] 健康检查通过 - [ ] 日志显示服务正常启动 - [ ] 记录内网IP地址 - [ ] 更新Node.js后端环境变量 --- ### D. 成本预估 **测试环境（轻量版SAE?*?``` 规格??GB × 1实例 费用：约 ¥60/?``` **优化建议**?- 测试阶段可以手动停止应用（停止后不计费） - 夜间或周末停止应用节省成?- 生产环境建议使用包年包月优惠 --- ### E. 相关文档 - [部署进度总览](./00-部署进度总览.md) - 所有资源速查?- [Python微服?SAE容器部署指南](./04-Python微服?SAE容器部署指南.md) - 技术架构详?- [快速部署SOP](./01-快速部署SOP-零基础?md) - 完整部署流程 --- **文档维护**?- 创建时间?024-12-24 - 最后更新：2024-12-24 - 下次审查?025-01-24 --- **部署完成后，请记录以下信?*? ``` 部署时间?024-12-24 19:43 内网IP地址：http://172.17.173.66:8000 首次健康检查通过时间?024-12-24 19:44 SAE应用名称：python-extraction-test 应用类型：轻量版应用 规格配置??GB × 1实例 部署状态：?成功 备注?- 解决了ACR镜像拉取权限问题（配置了镜像仓库认证?- 解决了镜像标签问题（指定?v1.0版本?- 应用正常运行?个uvicorn worker进程 - OpenBLAS警告可忽略（不影响功能） ``` --- > **提示**：部署完成后，请及时更新 [部署进度总览.md](./00-部署进度总览.md) 中的内网地址?