Azure App Service 部署(Node.js)
本技能阐述了将 Node.js 应用程序部署到 Azure App Service (Linux) 并通过托管标识安全连接到 Azure AI Foundry 代理的完美最佳实践路径。
1. 云基础设施设置
- App Service 计划: 对于生产环境,始终选择专用层级(例如 Basic B1)。免费 (F1) 层级有严格的每日 60 分钟 CPU 配额,会导致应用程序被强制关闭(返回
403 Stopped错误)。
2. 身份验证与托管标识(无密码)
- 代码: 在 Node.js 后端中使用
@azure/identity的DefaultAzureCredential。 - 启用标识: 在 Azure App Service 门户中,进入 设置 > 标识,然后启用 系统分配。
- IAM 权限: 在目标 Azure AI 项目中,进入 访问控制 (IAM),并将 Azure AI 开发者 角色分配给 App Service 的托管标识。(注意:对于 Azure Foundry 编排代理,
Cognitive Services OpenAI User权限不足。)
3. 环境变量(前后端陷阱)
当通过 GitHub Actions 部署全栈应用(React/Vite + Node.js)时,环境变量必须逻辑分离:
前端(Vite)
- 以
VITE_为前缀的变量(例如 Supabase 密钥)在构建时被打包到静态 HTML/JS 中。 - 设置位置: 它们必须存储在 GitHub Secrets 中,并在
.github/workflows文件中npm run build步骤的env:块内显式映射。 - 危险: 如果变量仅存在于 Azure 而 GitHub Actions 中没有,Vite 将使用空变量构建前端。
后端(Node.js)
- 实时的
server.js文件在运行时从云容器读取环境变量。 - 设置位置: 直接在 Azure 门户的 设置 > 环境变量 中配置变量(例如 Azure AI 端点、后端 Supabase 密钥)。
- 危险: Azure App Service 后端不会继承你的 GitHub Actions Secrets。你必须在 Azure 门户中手动设置它们。
- 关键: 变量在 Node.js 进程启动时仅加载到内存一次。如果添加或修改变量,你必须在 App Service 概览页面上显式点击重启。
- 要信任 Azure 负载均衡器(
express-rate-limit需要),请确保 Express 应用包含app.set('trust proxy', 1);。
4. GitHub Actions CI/CD 流水线
最安全的部署策略是避免冲突的构建引擎(GitHub vs. Azure Oryx)。让 GitHub 100% 执行构建和打包。
工作流最佳实践:
- GitHub 运行
npm install和前端构建(npm run build)。 - GitHub 上传包含编译输出(
dist)、后端文件(server.js)以及至关重要的是node_modules文件夹的构件。- 为什么? 如果省略了
node_modules,Azure 的 Oryx 引擎会尝试通过执行npm run build自行构建应用,这将因为未上传原始源文件(index.html)而崩溃。
- 为什么? 如果省略了
- 使用带有存储在 GitHub Secret 中的发布配置文件的
azure/webapps-deploy@v3。