AI 应用部署与工程化入门

写完代码只是第一步。部署与工程化要解决的是：如何让同一份应用在不同环境中稳定运行，如何安全发布新版本，以及出现问题后如何快速发现和恢复。

一、从代码到线上服务

一套基础发布流程通常包含：

提交代码
  ↓
自动测试
  ↓
构建应用或镜像
  ↓
部署到目标环境
  ↓
健康检查
  ↓
日志与指标监控

每一步都应该可以重复执行，并尽量减少人工操作。

二、使用 Docker 容器化

容器会把应用、运行环境和依赖打包在一起，从而减少“本地可以运行、服务器不能运行”的差异。

一个简单的 FastAPI Dockerfile：

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

构建并运行：

docker build -t zcoco-api:latest .
docker run --rm -p 8000:8000 zcoco-api:latest

建议同时添加 .dockerignore，排除虚拟环境、缓存、日志和本地密钥。

三、环境变量与配置

开发、测试和生产环境的地址与密钥通常不同，不应该直接写死在代码里。

import os

database_url = os.environ["DATABASE_URL"]
model_api_key = os.environ["MODEL_API_KEY"]

基本原则：

配置可以通过环境变量注入。
.env 文件只用于本地开发，不提交真实密钥。
生产密钥存放在部署平台的 Secrets 中。
应用启动时检查必要配置是否存在。

四、CI/CD 自动化部署

CI 负责自动检查代码，CD 负责把通过检查的版本发布到目标环境。

一个简化的 GitHub Actions 流程：

name: test

on:
  push:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt
      - run: pytest -q

生产部署前至少应该通过：

依赖安装。
静态检查。
自动化测试。
构建验证。
健康检查。

五、健康检查与日志

健康检查用于判断服务是否仍然可以处理请求：

@app.get("/health")
def health_check():
    return {"status": "ok"}

日志应至少记录：

请求时间和请求标识。
接口路径、状态码与耗时。
外部模型或数据库调用结果。
可定位问题的异常信息。

不要在日志中记录密码、访问令牌、身份证号或完整用户隐私数据。

六、监控哪些指标

最基础的监控可以关注：

可用性：服务是否存活。
延迟：接口和模型调用耗时。
错误率：失败请求所占比例。
流量：每分钟请求数量。
资源：CPU、内存、磁盘和网络。
AI 指标：Token 消耗、检索耗时和模型失败率。

日志告诉我们“发生了什么”，指标告诉我们“系统整体是否异常”。

七、安全基础

所有公网服务使用 HTTPS。
密钥通过 Secrets 管理并定期轮换。
接口增加身份认证和权限校验。
对上传文件限制类型与大小。
对高频接口增加限流。
及时更新有安全漏洞的依赖。
数据库账号只授予所需的最小权限。

安全不是上线前的一次检查，而是整个开发和运行周期中的持续工作。

八、发布与回滚

每次发布都应该有明确版本，并保留上一个可用版本。当新版本出现严重错误时，可以快速回滚，而不是在线上临时修改代码。

推荐发布步骤：

为版本生成唯一编号。
先部署到测试或预览环境。
执行自动测试和关键路径检查。
发布到生产环境。
观察错误率、延迟和日志。
发现异常时立即回滚。

九、学习检查清单

能编写 Dockerfile 并运行容器。
能使用环境变量管理配置。
理解 CI 和 CD 分别解决什么问题。
能添加健康检查和结构化日志。
知道需要监控哪些基础指标。
能说明密钥管理、最小权限和回滚的重要性。

完成这些内容后，可以继续学习 Docker Compose、反向代理、云平台部署、Kubernetes 和完整的可观测性体系。