AI编程 Docker部署教程｜附源码

随着大模型技术的快速发展，越来越多开发者开始尝试将 AI 能力集成到自己的应用中，例如：AI 聊天助手、代码生成工具、智能客服、知识库问答系统、自动化脚本生成平台等。

在本地开发阶段，我们通常可以直接运行 Python、Node.js 或 Java 项目；但一旦要部署到服务器，就会遇到一系列问题：

• 服务器环境和本地环境不一致；
• Python 或 Node.js 版本冲突；
• 依赖安装失败；
• 项目迁移困难；
• 多服务部署复杂；
• 更新版本时容易出错。

这时，Docker 就成为 AI 应用部署中非常重要的工具。通过 Docker，我们可以将项目代码、运行环境、依赖包、启动命令统一打包成镜像，在任何支持 Docker 的服务器上快速运行。

本文将以一个简单的 AI 编程助手项目 为例，完整演示如何使用 Docker 进行部署，并附上完整源码示例。

一、项目介绍

本文实现的是一个简单的 AI 编程助手后端服务，主要功能包括：

1. 提供 HTTP API 接口；
2. 接收用户输入的编程问题；
3. 调用大模型 API；
4. 返回 AI 生成的代码或解释；
5. 使用 Docker 完成容器化部署；
6. 使用 Docker Compose 简化运行流程。

为了方便演示，本文使用 Python + FastAPI 构建后端服务。FastAPI 具有性能高、语法简洁、自动生成接口文档等优点，非常适合构建 AI API 服务。

项目最终目录结构如下：

ai-code-assistant/
├── app/
│   ├── main.py
│   ├── ai_service.py
│   └── config.py
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env
└── README.md

二、准备工作

在开始之前，你需要准备以下环境：

1. 本地开发环境

建议安装：

• Python 3.10+
• Docker
• Docker Compose
• Git
• VS Code 或其他代码编辑器

可以通过以下命令检查 Docker 是否安装成功：

docker -v

如果输出类似下面内容，说明安装成功：

Docker version 24.0.0, build xxxxx

检查 Docker Compose：

docker compose version

2. AI API Key

如果你的 AI 项目需要调用第三方大模型服务，例如 OpenAI、通义千问、智谱、DeepSeek、Claude 等，通常都需要配置 API Key。

本文为了通用性，代码中使用环境变量读取 API Key：

AI_API_KEY=你的_API_KEY
AI_BASE_URL=https://api.example.com/v1
AI_MODEL=your-model-name

你可以根据实际使用的大模型服务修改对应地址和模型名称。

三、创建项目目录

首先创建项目目录：

mkdir ai-code-assistant
cd ai-code-assistant

创建 app 目录：

mkdir app

最终我们会把后端核心代码放到 app 目录中。

四、编写配置文件

在 app 目录下创建 config.py：

import os
from dotenv import load_dotenv

load_dotenv()


class Settings:
    AI_API_KEY: str = os.getenv("AI_API_KEY", "")
    AI_BASE_URL: str = os.getenv("AI_BASE_URL", "")
    AI_MODEL: str = os.getenv("AI_MODEL", "gpt-4o-mini")
    APP_HOST: str = os.getenv("APP_HOST", "0.0.0.0")
    APP_PORT: int = int(os.getenv("APP_PORT", "8000"))


settings = Settings()

这个文件的作用是统一读取环境变量，避免把 API Key 写死在代码中。

在真实项目中，不建议将 API Key 提交到 Git 仓库，否则容易造成密钥泄露。

五、编写 AI 调用服务

继续在 app 目录下创建 ai_service.py：

import requests
from app.config import settings


def generate_code(prompt: str) -> str:
    """
    调用大模型接口，根据用户输入生成代码或编程解释。
    """

    if not settings.AI_API_KEY:
        return "错误：未配置 AI_API_KEY，请在 .env 文件或环境变量中设置。"

    url = f"{settings.AI_BASE_URL}/chat/completions"

    headers = {
        "Authorization": f"Bearer {settings.AI_API_KEY}",
        "Content-Type": "application/json"
    }

    payload = {
        "model": settings.AI_MODEL,
        "messages": [
            {
                "role": "system",
                "content": "你是一名资深软件工程师，擅长 Python、JavaScript、Docker、Linux 和后端开发。请用清晰、准确、可运行的方式回答用户的编程问题。"
            },
            {
                "role": "user",
                "content": prompt
            }
        ],
        "temperature": 0.3
    }

    try:
        response = requests.post(url, json=payload, headers=headers, timeout=60)
        response.raise_for_status()
        data = response.json()

        return data["choices"][0]["message"]["content"]

    except requests.exceptions.RequestException as e:
        return f"请求 AI 服务失败：{str(e)}"
    except Exception as e:
        return f"解析 AI 返回结果失败：{str(e)}"

这里使用了类似 OpenAI Chat Completions 的接口格式。如果你使用的是其他平台，需要根据对应平台文档调整请求地址和返回字段。

例如有的平台接口路径不是 /chat/completions，也有的平台鉴权方式不是 Bearer Token，这些都需要按实际情况修改。

六、编写 FastAPI 主程序

在 app 目录下创建 main.py：

from fastapi import FastAPI
from pydantic import BaseModel
from app.ai_service import generate_code


app = FastAPI(
    title="AI 编程助手 API",
    description="一个基于 FastAPI 和 Docker 部署的 AI 编程助手示例项目",
    version="1.0.0"
)


class CodeRequest(BaseModel):
    prompt: str


class CodeResponse(BaseModel):
    result: str


@app.get("/")
def index():
    return {
        "message": "AI 编程助手服务运行中",
        "docs": "/docs"
    }


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


@app.post("/api/generate", response_model=CodeResponse)
def generate(request: CodeRequest):
    result = generate_code(request.prompt)
    return {
        "result": result
    }

这个文件提供了三个接口：

FastAPI 默认会提供 Swagger 文档，访问地址为：

http://localhost:8000/docs

七、编写依赖文件

在项目根目录创建 requirements.txt：

fastapi==0.111.0
uvicorn[standard]==0.30.1
requests==2.32.3
python-dotenv==1.0.1
pydantic==2.7.4

这些依赖分别用于：

• fastapi：构建 Web API；
• uvicorn：ASGI 服务启动器；
• requests：发送 HTTP 请求；
• python-dotenv：读取 .env 环境变量；
• pydantic：数据校验和模型定义。

八、编写环境变量文件

在项目根目录创建 .env 文件：

AI_API_KEY=你的_API_KEY
AI_BASE_URL=https://api.example.com/v1
AI_MODEL=gpt-4o-mini
APP_HOST=0.0.0.0
APP_PORT=8000

请注意：

1. 不要把真实 API Key 上传到公开仓库；
2. 可以创建 .gitignore 忽略 .env 文件；
3. 生产环境更推荐使用服务器环境变量或 Docker Secret。

建议创建 .gitignore：

.env
__pycache__/
*.pyc
.venv/
.idea/
.vscode/

九、本地运行测试

在使用 Docker 之前，我们可以先在本地直接运行项目，确认代码没有问题。

安装依赖：

pip install -r requirements.txt

启动服务：

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

访问浏览器：

http://localhost:8000

如果看到如下返回，说明服务启动成功：

{
  "message": "AI 编程助手服务运行中",
  "docs": "/docs"
}

访问接口文档：

http://localhost:8000/docs

你可以在 Swagger 页面中测试 /api/generate 接口。

请求示例：

{
  "prompt": "请用 Python 写一个快速排序算法，并解释每一步。"
}

返回示例：

{
  "result": "下面是一个 Python 快速排序示例..."
}

十、编写 Dockerfile

Dockerfile 是 Docker 构建镜像的核心文件。它描述了镜像如何构建、依赖如何安装、服务如何启动。

在项目根目录创建 Dockerfile：

FROM python:3.11-slim

WORKDIR /app

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

COPY requirements.txt .

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

COPY . .

EXPOSE 8000

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

逐行解释如下：

FROM python:3.11-slim

表示使用 Python 3.11 的精简版镜像作为基础镜像。

WORKDIR /app

设置容器内工作目录为 /app。

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

这两个环境变量常用于 Python 容器：

• PYTHONDONTWRITEBYTECODE=1：不生成 .pyc 文件；
• PYTHONUNBUFFERED=1：让日志实时输出，方便 Docker 查看日志。

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

先复制依赖文件并安装依赖。这样做的好处是可以利用 Docker 构建缓存，只要依赖文件不变，后续构建会更快。

COPY . .

复制项目代码到容器中。

EXPOSE 8000

声明容器服务端口。

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

容器启动后执行的命令。

十一、构建 Docker 镜像

在项目根目录执行：

docker build -t ai-code-assistant:1.0 .

参数说明：

• docker build：构建镜像；
• -t ai-code-assistant:1.0：指定镜像名称和版本；
• .：表示使用当前目录作为构建上下文。

构建完成后查看镜像：

docker images

你应该能看到类似结果：

REPOSITORY          TAG       IMAGE ID       CREATED        SIZE
ai-code-assistant   1.0       xxxxxxxx       1 minute ago   180MB

十二、使用 Docker 运行容器

可以通过以下命令启动容器：

docker run -d \
  --name ai-code-assistant \
  -p 8000:8000 \
  --env-file .env \
  ai-code-assistant:1.0

参数说明：

查看运行状态：

docker ps

查看日志：

docker logs -f ai-code-assistant

测试健康检查：

curl http://localhost:8000/health

如果返回：

{
  "status": "ok"
}

说明 Docker 部署成功。

十三、使用 Docker Compose 部署

单独使用 docker run 没问题，但参数较长，不方便维护。实际项目中更推荐使用 Docker Compose。

在项目根目录创建 docker-compose.yml：

services:
  ai-code-assistant:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: ai-code-assistant
    ports:
      - "8000:8000"
    env_file:
      - .env
    restart: always

启动服务：

docker compose up -d

查看服务：

docker compose ps

查看日志：

docker compose logs -f

停止服务：

docker compose down

重新构建并启动：

docker compose up -d --build

Docker Compose 的好处是配置清晰，适合管理多个服务。例如后续你要加入 Redis、PostgreSQL、向量数据库、Nginx，都可以写在同一个 docker-compose.yml 中。

十四、完整源码汇总

下面给出完整源码，方便你直接复制使用。

1. app/config.py

import os
from dotenv import load_dotenv

load_dotenv()


class Settings:
    AI_API_KEY: str = os.getenv("AI_API_KEY", "")
    AI_BASE_URL: str = os.getenv("AI_BASE_URL", "")
    AI_MODEL: str = os.getenv("AI_MODEL", "gpt-4o-mini")
    APP_HOST: str = os.getenv("APP_HOST", "0.0.0.0")
    APP_PORT: int = int(os.getenv("APP_PORT", "8000"))


settings = Settings()

2. app/ai_service.py

import requests
from app.config import settings


def generate_code(prompt: str) -> str:
    if not settings.AI_API_KEY:
        return "错误：未配置 AI_API_KEY，请在 .env 文件或环境变量中设置。"

    url = f"{settings.AI_BASE_URL}/chat/completions"

    headers = {
        "Authorization": f"Bearer {settings.AI_API_KEY}",
        "Content-Type": "application/json"
    }

    payload = {
        "model": settings.AI_MODEL,
        "messages": [
            {
                "role": "system",
                "content": "你是一名资深软件工程师，擅长 Python、JavaScript、Docker、Linux 和后端开发。"
            },
            {
                "role": "user",
                "content": prompt
            }
        ],
        "temperature": 0.3
    }

    try:
        response = requests.post(url, json=payload, headers=headers, timeout=60)
        response.raise_for_status()
        data = response.json()
        return data["choices"][0]["message"]["content"]
    except requests.exceptions.RequestException as e:
        return f"请求 AI 服务失败：{str(e)}"
    except Exception as e:
        return f"解析 AI 返回结果失败：{str(e)}"

3. app/main.py

from fastapi import FastAPI
from pydantic import BaseModel
from app.ai_service import generate_code


app = FastAPI(
    title="AI 编程助手 API",
    description="基于 FastAPI 和 Docker 部署的 AI 编程助手",
    version="1.0.0"
)


class CodeRequest(BaseModel):
    prompt: str


class CodeResponse(BaseModel):
    result: str


@app.get("/")
def index():
    return {
        "message": "AI 编程助手服务运行中",
        "docs": "/docs"
    }


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


@app.post("/api/generate", response_model=CodeResponse)
def generate(request: CodeRequest):
    result = generate_code(request.prompt)
    return {
        "result": result
    }

4. requirements.txt

fastapi==0.111.0
uvicorn[standard]==0.30.1
requests==2.32.3
python-dotenv==1.0.1
pydantic==2.7.4

5. .env

AI_API_KEY=你的_API_KEY
AI_BASE_URL=https://api.example.com/v1
AI_MODEL=gpt-4o-mini
APP_HOST=0.0.0.0
APP_PORT=8000

6. Dockerfile

FROM python:3.11-slim

WORKDIR /app

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

COPY requirements.txt .

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

COPY . .

EXPOSE 8000

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

7. docker-compose.yml

services:
  ai-code-assistant:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: ai-code-assistant
    ports:
      - "8000:8000"
    env_file:
      - .env
    restart: always

十五、部署到云服务器

如果你要部署到云服务器，例如阿里云、腾讯云、华为云、AWS、Vultr 等，可以参考以下流程。

1. 登录服务器

ssh root@你的服务器IP

2. 安装 Docker

以 Ubuntu 为例：

apt update
apt install -y docker.io docker-compose-plugin
systemctl enable docker
systemctl start docker

检查版本：

docker -v
docker compose version

3. 上传项目代码

方式一：使用 Git 拉取：

git clone https://你的仓库地址/ai-code-assistant.git
cd ai-code-assistant

方式二：使用 scp 上传：

scp -r ai-code-assistant root@你的服务器IP:/root/

4. 配置环境变量

进入项目目录后创建 .env：

nano .env

写入：

AI_API_KEY=你的真实_API_KEY
AI_BASE_URL=https://api.example.com/v1
AI_MODEL=gpt-4o-mini
APP_HOST=0.0.0.0
APP_PORT=8000

5. 启动服务

docker compose up -d --build

6. 开放服务器端口

如果使用云服务器，需要在安全组中开放 8000 端口。

然后访问：

http://你的服务器IP:8000

接口文档：

http://你的服务器IP:8000/docs

十六、生产环境优化建议

上面的示例适合入门和小型项目。如果用于生产环境，建议继续做以下优化。

1. 使用 Nginx 反向代理

不要直接暴露 FastAPI 服务端口，可以使用 Nginx 做反向代理，并配置 HTTPS。

例如：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

2. 配置 HTTPS

可以使用 Certbot 免费申请 Let’s Encrypt 证书：

apt install -y certbot python3-certbot-nginx
certbot --nginx

3. 增加接口鉴权

AI 接口通常会消耗费用，因此不能随便公开。可以增加 Token 鉴权、用户登录、接口限流等能力。

简单方式是在请求头中添加自定义 Token，例如：

Authorization: Bearer your-service-token

4. 增加日志系统

生产环境建议记录：

• 请求时间；
• 请求 IP；
• 请求路径；
• AI 模型耗时；
• 错误信息；
• Token 消耗量。

可以接入 ELK、Grafana Loki 或云厂商日志服务。

5. 增加超时和重试机制

调用大模型 API 时，网络波动和服务限流都很常见。建议增加：

• 请求超时；
• 自动重试；
• 指数退避；
• 错误码分类处理。

6. 使用异步请求

如果并发量较高，可以将 requests 替换为 httpx.AsyncClient，并将接口改为异步接口，从而提升并发处理能力。

7. 增加缓存

对于重复问题，可以使用 Redis 缓存结果，减少重复调用模型的成本。

8. 使用多 Worker

生产环境中，可以使用 Gunicorn 管理多个 Uvicorn Worker：

gunicorn app.main:app \
  -k uvicorn.workers.UvicornWorker \
  -w 4 \
  -b 0.0.0.0:8000

对应 Dockerfile 的启动命令也可以改成 Gunicorn。

十七、常见问题排查

1. 容器启动后访问不了

检查容器是否运行：

docker ps

检查日志：

docker logs -f ai-code-assistant

确认端口映射是否正确：

-p 8000:8000

确认云服务器安全组是否开放端口。

2. 提示未配置 API Key

检查 .env 是否存在：

ls -a

检查 Docker Compose 是否加载：

env_file:
  - .env

修改 .env 后需要重启：

docker compose down
docker compose up -d

3. AI 接口请求失败

可能原因包括：

• AI_BASE_URL 填写错误；
• API Key 无效；
• 模型名称错误；
• 账户余额不足；
• 网络无法访问对应服务；
• 请求格式与平台不兼容。

可以进入容器测试网络：

docker exec -it ai-code-assistant bash

然后使用：

curl https://api.example.com/v1

4. 修改代码后没有生效

Docker 镜像不会自动包含你修改后的代码，需要重新构建：

docker compose up -d --build

如果仍然不生效，可以清理旧镜像：

docker compose down
docker image prune -f
docker compose up -d --build

十八、总结

本文从零开始完成了一个 AI 编程助手项目，并演示了如何使用 Docker 和 Docker Compose 进行部署。

完整流程包括：

1. 使用 FastAPI 编写 AI 后端接口；
2. 使用环境变量管理 API Key；
3. 编写 requirements.txt 管理依赖；
4. 编写 Dockerfile 构建镜像；
5. 使用 docker run 启动容器；
6. 使用 Docker Compose 简化部署；
7. 部署到云服务器；
8. 给出生产环境优化方向。

Docker 的核心价值在于：一次构建，到处运行。对于 AI 应用来说，它可以大幅降低环境配置成本，让开发者更专注于模型能力、业务逻辑和产品体验。

如果你正在开发 AI 编程助手、AI 知识库、智能客服、AI Agent 或自动化代码生成平台，那么 Docker 几乎是上线部署过程中不可或缺的一环。通过本文的源码和步骤，你可以快速搭建属于自己的 AI 编程服务，并在此基础上继续扩展前端页面、用户系统、数据库、知识库检索和更多智能化能力。