阶段2(下):运维专题 Docker/Nginx/Linux/CI-CD/Git 的课程、企业场景、面试题和可运行示例
This commit is contained in:
1 parent
5eb67c5d08
commit
b8010a74f3
42 files changed
+3533
-55
No files matched your search
@@ -0,0 +1,93 @@
|
||||
---
|
||||
id: devops.docker.image-dockerfile
|
||||
title: 镜像和 Dockerfile:分层缓存、多阶段构建、非 root、信号处理
|
||||
type: lesson
|
||||
domain: devops
|
||||
stack: [docker]
|
||||
tags: [Dockerfile, 多阶段构建, 镜像分层, 构建缓存, distroless]
|
||||
level: basic
|
||||
est_hours: 3
|
||||
related: [devops.docker.compose-network-volume, devops.docker.interview]
|
||||
week: [3, 6]
|
||||
order: 1
|
||||
---
|
||||
|
||||
# 镜像和 Dockerfile:分层缓存、多阶段构建、非 root、信号处理
|
||||
|
||||
## 解释说明
|
||||
|
||||
- **镜像 vs 容器**:镜像是只读的模板(像“类”),容器是镜像运行起来的实例(像“对象”),容器在镜像之上加一个可写层。
|
||||
- **分层**:Dockerfile 中 `RUN`、`COPY`、`ADD` 每条指令产生一层。构建时如果某一层的输入没变,就直接用缓存;**某一层变了,它后面的层全部重新构建**。所以把变化少的放前面(安装依赖),变化多的放后面(复制源码)。
|
||||
- **多阶段构建**:第一阶段用带完整工具链的镜像编译,第二阶段只复制编译产物到很小的运行镜像。Go 编译成静态二进制后,运行镜像可以是 `distroless` 甚至 `scratch`,体积从几百 MB 降到十几 MB,攻击面也小。
|
||||
- **`.dockerignore`**:排除 `.git`、`node_modules`、本地数据,减少构建上下文、避免把密钥打进镜像。
|
||||
- **非 root 运行**:`USER` 指定普通用户,容器被攻破时影响更小。
|
||||
- **PID 1 和信号**:`ENTRYPOINT ["/api"]`(exec 形式)让程序直接成为 PID 1,能收到 `docker stop` 发出的 SIGTERM 做优雅退出;`ENTRYPOINT /api`(shell 形式)会让 `/bin/sh` 成为 PID 1,信号传不到程序,最后被强制 kill。
|
||||
- **`CMD` vs `ENTRYPOINT`**:`ENTRYPOINT` 是固定执行的程序,`CMD` 是默认参数(运行时可以覆盖)。
|
||||
|
||||
**常用命令**:`docker build -t api:1.0 .`、`docker run -d -p 8080:8080 --name api api:1.0`、`docker logs -f api`、`docker exec -it api sh`(distroless 没有 shell)、`docker images`、`docker history api:1.0`(看每层大小)。
|
||||
|
||||
## 案例
|
||||
|
||||
Go 服务最初用 `FROM golang` 单阶段构建,镜像 800MB+,每次改一行代码都要重新下载依赖。改成:先 `COPY go.mod go.sum` 再 `go mod download`(依赖层可缓存)→ 再复制源码编译 → 运行阶段用 distroless,镜像十几 MB,代码改动时构建只需重新编译。
|
||||
|
||||
Python(FastAPI)服务同理:先复制 `requirements.txt` / `pyproject.toml` 安装依赖,再复制源码;用 `python:3.12-slim` 作为基础镜像。
|
||||
|
||||
## 代码示例
|
||||
|
||||
Go 服务的多阶段 Dockerfile(完整示例见 [examples/go-api-compose](examples/go-api-compose/)):
|
||||
|
||||
```dockerfile
|
||||
# syntax=docker/dockerfile:1
|
||||
FROM golang:1.26-alpine AS build
|
||||
WORKDIR /src
|
||||
COPY go.mod go.sum ./
|
||||
RUN go mod download # 依赖层:go.mod 不变就用缓存
|
||||
COPY . .
|
||||
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/api .
|
||||
|
||||
FROM gcr.io/distroless/static-debian12:nonroot
|
||||
COPY --from=build /out/api /api
|
||||
USER nonroot:nonroot
|
||||
EXPOSE 8080
|
||||
ENTRYPOINT ["/api"] # exec 形式:能收到 SIGTERM
|
||||
```
|
||||
|
||||
Python FastAPI 服务(示意,按项目实际的依赖文件调整):
|
||||
|
||||
```dockerfile
|
||||
FROM python:3.12-slim
|
||||
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
|
||||
WORKDIR /app
|
||||
COPY requirements.txt .
|
||||
RUN pip install --no-cache-dir -r requirements.txt
|
||||
COPY app ./app
|
||||
RUN useradd -m appuser
|
||||
USER appuser
|
||||
EXPOSE 8000
|
||||
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
|
||||
```
|
||||
|
||||
Go 程序里配合优雅退出:
|
||||
|
||||
```go
|
||||
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
|
||||
defer stop()
|
||||
go srv.ListenAndServe()
|
||||
<-ctx.Done() // 收到 docker stop 的 SIGTERM
|
||||
shutdownCtx, cancel := context.WithTimeout(context.Background(), 8*time.Second)
|
||||
defer cancel()
|
||||
srv.Shutdown(shutdownCtx) // 等正在处理的请求完成
|
||||
```
|
||||
|
||||
## 易错点
|
||||
|
||||
- **`COPY . .` 放在安装依赖之前**:每次改代码都重新安装依赖,构建很慢。
|
||||
- **把密钥写进 Dockerfile 或复制进镜像**:镜像的每一层都能被查看,删掉的文件也还在之前的层里。密钥通过运行时环境变量或密钥管理注入。
|
||||
- **使用 `latest` 标签**:不知道实际跑的是哪个版本,无法回滚。用版本号或 Git 提交哈希。
|
||||
- **服务监听 `127.0.0.1`**:容器外访问不到,要监听 `0.0.0.0`。
|
||||
- **shell 形式的 ENTRYPOINT**:收不到 SIGTERM,每次停止都要等 10 秒后被强杀,正在处理的请求被中断。
|
||||
- **CGO 编译的二进制放进 scratch / distroless static**:缺少 libc 运行不起来,要 `CGO_ENABLED=0` 或换带 libc 的基础镜像。
|
||||
|
||||
## 面试常问
|
||||
|
||||
见 [Docker 面试题](interview.md):镜像和容器的区别、分层与缓存、多阶段构建、如何减小镜像体积、CMD 和 ENTRYPOINT。
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
id: devops.docker.compose-network-volume
|
||||
title: Compose、网络和数据卷:多服务编排、健康检查、环境变量
|
||||
type: lesson
|
||||
domain: devops
|
||||
stack: [docker]
|
||||
tags: [Compose, 网络, 数据卷, 健康检查, 环境变量]
|
||||
level: basic
|
||||
prerequisites: [devops.docker.image-dockerfile]
|
||||
est_hours: 2
|
||||
related: [devops.docker.scenario.compose-dev-env, devops.docker.interview]
|
||||
week: [3, 6, 13]
|
||||
order: 2
|
||||
---
|
||||
|
||||
# Compose、网络和数据卷:多服务编排、健康检查、环境变量
|
||||
|
||||
## 解释说明
|
||||
|
||||
- **Compose**:用一个 `compose.yaml` 描述多个服务(应用、数据库、缓存),`docker compose up -d` 一起启动。适合本地开发、测试环境和小规模单机部署;多机、大规模用 Kubernetes。
|
||||
- **网络**:Compose 默认为项目创建一个网络,服务之间**用服务名当主机名**访问(`db:5432`),不需要知道 IP。容器内的 `localhost` 指的是容器自己,不是宿主机。
|
||||
- **端口映射**:`ports: "8080:8080"` 是“宿主机端口:容器端口”,只有需要从宿主机访问的服务才映射。数据库不映射端口更安全(只在内部网络可见)。
|
||||
- **数据卷**:容器删除后可写层的数据就没了。数据库数据要放在**命名卷**(Docker 管理)或**绑定挂载**(宿主机目录,开发时挂源码目录方便热更新)。
|
||||
- **健康检查和启动顺序**:`depends_on` 默认只保证“先启动”,不保证“已就绪”。给数据库配 `healthcheck`,应用用 `condition: service_healthy` 等待。应用本身也要有连接重试。
|
||||
- **环境变量**:`environment` 直接写,或 `env_file: .env`;`.env` 文件不要提交到 Git。Compose 文件里 `${VAR}` 会从 shell 或项目目录的 `.env` 读取。
|
||||
|
||||
**常用命令**:`docker compose up -d --build`、`docker compose ps`、`docker compose logs -f api`、`docker compose exec db psql -U app`、`docker compose down`(加 `-v` 会删除数据卷,小心)。
|
||||
|
||||
## 案例
|
||||
|
||||
开发 RAG 服务时需要 PostgreSQL(含 pgvector)+ Redis + 应用。用 Compose:新同事 clone 仓库后 `docker compose up -d` 就能跑;数据库数据存在命名卷里,重启不丢;`db` 不映射端口,需要调试时临时 `docker compose exec db psql`。
|
||||
|
||||
## 代码示例
|
||||
|
||||
完整文件见 [examples/go-api-compose/compose.yaml](examples/go-api-compose/compose.yaml):
|
||||
|
||||
```yaml
|
||||
services:
|
||||
api:
|
||||
build: .
|
||||
ports:
|
||||
- "8080:8080"
|
||||
environment:
|
||||
DATABASE_URL: postgres://app:app@db:5432/app?sslmode=disable # 用服务名 db 访问
|
||||
REDIS_URL: redis://redis:6379/0
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_started
|
||||
restart: unless-stopped
|
||||
|
||||
db:
|
||||
image: postgres:17
|
||||
environment:
|
||||
POSTGRES_USER: app
|
||||
POSTGRES_PASSWORD: app
|
||||
POSTGRES_DB: app
|
||||
volumes:
|
||||
- pgdata:/var/lib/postgresql/data
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U app -d app"]
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 10
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
|
||||
volumes:
|
||||
pgdata:
|
||||
```
|
||||
|
||||
## 易错点
|
||||
|
||||
- **应用里连 `localhost:5432`**:在容器里 localhost 是应用容器自己,要用服务名 `db`。
|
||||
- **以为 `depends_on` 会等数据库就绪**:只等容器启动。要配健康检查,应用也要能重试连接。
|
||||
- **`docker compose down -v`**:会删掉命名卷,数据库数据全没。
|
||||
- **把数据库端口映射到公网服务器的 `0.0.0.0`**:数据库直接暴露在公网。不映射,或者只绑定 `127.0.0.1:5432:5432`。
|
||||
- **在 compose 文件里写真实密码并提交**:用 `.env`(加入 `.gitignore`)或部署平台的密钥管理。
|
||||
- **镜像版本升级时数据目录变化**:例如 PostgreSQL 新大版本的数据目录约定可能变化,升级前看官方镜像说明并备份。
|
||||
|
||||
## 面试常问
|
||||
|
||||
见 [Docker 面试题](interview.md):容器之间怎么通信、数据怎么持久化、depends_on 的局限。
|
||||
@@ -0,0 +1,4 @@
|
||||
.git
|
||||
*.md
|
||||
*_test.go
|
||||
compose.yaml
|
||||
@@ -0,0 +1,19 @@
|
||||
# syntax=docker/dockerfile:1
|
||||
# ---------- 构建阶段:带完整 Go 工具链 ----------
|
||||
FROM golang:1.26-alpine AS build
|
||||
WORKDIR /src
|
||||
# 先只复制依赖描述文件,依赖不变时这一层可以复用缓存
|
||||
COPY go.mod ./
|
||||
RUN go mod download
|
||||
COPY . .
|
||||
# 静态编译,去掉调试信息减小体积
|
||||
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/api .
|
||||
|
||||
# ---------- 运行阶段:只放二进制 ----------
|
||||
FROM gcr.io/distroless/static-debian12:nonroot
|
||||
COPY --from=build /out/api /api
|
||||
ENV PORT=8080
|
||||
EXPOSE 8080
|
||||
USER nonroot:nonroot
|
||||
# exec 形式,进程是 PID 1,能直接收到 SIGTERM
|
||||
ENTRYPOINT ["/api"]
|
||||
@@ -0,0 +1,36 @@
|
||||
# 本地开发环境:docker compose up -d --build
|
||||
# 镜像版本仅作示例,按项目需要调整
|
||||
services:
|
||||
api:
|
||||
build: .
|
||||
ports:
|
||||
- "8080:8080"
|
||||
environment:
|
||||
DATABASE_URL: postgres://app:app@db:5432/app?sslmode=disable # 服务名 db 就是主机名
|
||||
REDIS_URL: redis://redis:6379/0
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy # 等数据库健康检查通过再启动
|
||||
redis:
|
||||
condition: service_started
|
||||
restart: unless-stopped
|
||||
|
||||
db:
|
||||
image: postgres:17
|
||||
environment:
|
||||
POSTGRES_USER: app
|
||||
POSTGRES_PASSWORD: app # 仅限本地开发;生产用密钥管理
|
||||
POSTGRES_DB: app
|
||||
volumes:
|
||||
- pgdata:/var/lib/postgresql/data # 命名卷:容器删除后数据仍在
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U app -d app"]
|
||||
interval: 5s
|
||||
timeout: 3s
|
||||
retries: 10
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
|
||||
volumes:
|
||||
pgdata:
|
||||
@@ -0,0 +1,3 @@
|
||||
module example/goapi
|
||||
|
||||
go 1.22
|
||||
@@ -0,0 +1,54 @@
|
||||
// 一个最小的 Go HTTP 服务,用来演示多阶段构建、健康检查和优雅退出。
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"log"
|
||||
"net/http"
|
||||
"os"
|
||||
"os/signal"
|
||||
"syscall"
|
||||
"time"
|
||||
)
|
||||
|
||||
func newMux() *http.ServeMux {
|
||||
mux := http.NewServeMux()
|
||||
mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) {
|
||||
w.Write([]byte("ok"))
|
||||
})
|
||||
mux.HandleFunc("GET /api/hello", func(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
w.Write([]byte(`{"message":"hello from container"}`))
|
||||
})
|
||||
return mux
|
||||
}
|
||||
|
||||
func main() {
|
||||
addr := ":" + getenv("PORT", "8080")
|
||||
srv := &http.Server{Addr: addr, Handler: newMux(), ReadHeaderTimeout: 5 * time.Second}
|
||||
|
||||
// 容器停止时 Docker 先发 SIGTERM,等待一段时间(默认 10 秒)后才 SIGKILL
|
||||
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
|
||||
defer stop()
|
||||
go func() {
|
||||
log.Printf("listening on %s", addr)
|
||||
if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
|
||||
log.Fatal(err)
|
||||
}
|
||||
}()
|
||||
<-ctx.Done()
|
||||
shutdownCtx, cancel := context.WithTimeout(context.Background(), 8*time.Second)
|
||||
defer cancel()
|
||||
if err := srv.Shutdown(shutdownCtx); err != nil { // 不再接新请求,等正在处理的请求完成
|
||||
log.Printf("shutdown: %v", err)
|
||||
}
|
||||
log.Println("bye")
|
||||
}
|
||||
|
||||
func getenv(k, def string) string {
|
||||
if v := os.Getenv(k); v != "" {
|
||||
return v
|
||||
}
|
||||
return def
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestRoutes(t *testing.T) {
|
||||
srv := httptest.NewServer(newMux())
|
||||
defer srv.Close()
|
||||
for path, want := range map[string]int{"/healthz": 200, "/api/hello": 200, "/nope": 404} {
|
||||
resp, err := http.Get(srv.URL + path)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
resp.Body.Close()
|
||||
if resp.StatusCode != want {
|
||||
t.Errorf("%s = %d, want %d", path, resp.StatusCode, want)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -4,12 +4,39 @@ title: Docker 与 Compose
|
||||
type: index
|
||||
domain: devops
|
||||
stack: [docker]
|
||||
tags: []
|
||||
tags: [Docker, 容器, Compose, 镜像]
|
||||
week: [3, 6, 13, 14]
|
||||
---
|
||||
|
||||
# Docker 与 Compose
|
||||
|
||||
镜像、多阶段构建、网络、数据卷、Compose 编排。
|
||||
几乎所有后端和 AI 应用岗位都要求“会用 Docker 部署”。目标是:能写出体积小、可缓存、安全的 Dockerfile;能用 Compose 一条命令拉起“应用 + 数据库 + 缓存”的完整环境;能排查容器启动失败、连不上数据库等常见问题。
|
||||
|
||||
> 本专题建设中:课程、企业场景、面试题和示例代码会陆续补充。
|
||||
## 学习路线
|
||||
|
||||
| 顺序 | 课程 | 级别 | 预计 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | [镜像和 Dockerfile:分层缓存、多阶段构建、非 root、信号处理](01-image-dockerfile.md) | 基础 | 3 小时 |
|
||||
| 2 | [Compose、网络和数据卷:多服务编排、健康检查、环境变量](02-compose-network-volume.md) | 基础 | 2 小时 |
|
||||
|
||||
## 企业场景
|
||||
|
||||
- [一条命令拉起开发环境:Go API + Python AI 服务 + PostgreSQL + Redis](scenarios/compose-dev-env.md)
|
||||
|
||||
## 面试题
|
||||
|
||||
- [Docker 面试题](interview.md)
|
||||
|
||||
## 示例代码
|
||||
|
||||
- [examples/go-api-compose](examples/go-api-compose/):Go 服务(健康检查、优雅退出)+ 多阶段 Dockerfile + compose.yaml;Go 代码有测试,Dockerfile 需要本机安装 Docker 后自行构建验证
|
||||
|
||||
## 在 16 周计划中
|
||||
|
||||
- [第 3 周:项目一部署](../../../plan/week03-project1.md)、[第 6 周:RAG 服务容器化](../../../plan/week06-rag-2.md)、[第 13 周:Agent 部署](../../../plan/week13-agent-m4-eval-lowcode.md)、[第 14 周:部署](../../../plan/week14-backend-extend-deploy.md)
|
||||
|
||||
## 官方资料
|
||||
|
||||
- Docker 文档:https://docs.docker.com/
|
||||
- Dockerfile 参考:https://docs.docker.com/reference/dockerfile/
|
||||
- Compose 文件参考:https://docs.docker.com/reference/compose-file/
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
id: devops.docker.interview
|
||||
title: Docker 面试题
|
||||
type: interview
|
||||
domain: devops
|
||||
stack: [docker]
|
||||
tags: [Docker, 容器, Compose, 面试]
|
||||
level: basic
|
||||
related: [devops.docker.image-dockerfile, devops.docker.compose-network-volume]
|
||||
week: [3, 14, 16]
|
||||
---
|
||||
|
||||
# Docker 面试题
|
||||
|
||||
## 基础
|
||||
|
||||
### 【基础】容器和虚拟机有什么区别?
|
||||
|
||||
**参考答案**:虚拟机虚拟化硬件,每个虚拟机有自己完整的操作系统内核,隔离性强但启动慢、占用大;容器共享宿主机内核,靠 Linux 的 namespace 做隔离(进程、网络、文件系统等)、cgroups 限制资源,启动快、占用小,但隔离性比虚拟机弱。
|
||||
|
||||
### 【基础】镜像和容器是什么关系?镜像为什么要分层?
|
||||
|
||||
**参考答案**:镜像是只读模板,容器是镜像运行起来的实例,在镜像之上加了一个可写层。分层让多个镜像可以共享相同的底层(节省磁盘和下载),构建时没有变化的层可以复用缓存。
|
||||
|
||||
### 【基础】`CMD` 和 `ENTRYPOINT` 的区别?`COPY` 和 `ADD` 呢?
|
||||
|
||||
**参考答案**:`ENTRYPOINT` 指定容器启动时固定执行的程序;`CMD` 提供默认参数或默认命令,`docker run` 后面的参数会覆盖 `CMD`。两者都推荐使用 exec 形式(JSON 数组),程序作为 PID 1 才能收到信号。`COPY` 只复制本地文件;`ADD` 还能自动解压 tar 和下载 URL,行为不直观,一般用 `COPY`。
|
||||
|
||||
### 【基础】容器里的数据怎么持久化?
|
||||
|
||||
**参考答案**:容器可写层的数据随容器删除而消失。持久化用数据卷(Docker 管理的命名卷,适合数据库)或绑定挂载(把宿主机目录挂进容器,适合开发时挂源码、挂配置文件)。
|
||||
|
||||
## 进阶
|
||||
|
||||
### 【进阶】怎么减小镜像体积、加快构建?
|
||||
|
||||
**参考答案**:多阶段构建,运行阶段只保留产物;选小的基础镜像(slim、alpine、distroless);把变化少的步骤(安装依赖)放前面,充分利用层缓存;合并 RUN 并在同一层清理缓存(如 `pip install --no-cache-dir`);用 `.dockerignore` 排除无关文件。
|
||||
|
||||
### 【进阶】`docker stop` 时发生了什么?怎么做优雅退出?
|
||||
|
||||
**参考答案**:Docker 向容器的 PID 1 发送 SIGTERM,等待超时(默认 10 秒)后发送 SIGKILL。程序要监听 SIGTERM,停止接受新请求、处理完进行中的请求、关闭连接后退出。前提是程序本身是 PID 1(exec 形式启动),否则信号被 shell 吞掉。
|
||||
|
||||
### 【进阶】Compose 中服务之间怎么通信?`depends_on` 能保证依赖服务已就绪吗?
|
||||
|
||||
**参考答案**:同一个 Compose 项目的服务在同一个网络里,用服务名作为主机名访问。`depends_on` 默认只保证启动顺序,不保证就绪;要配合 `healthcheck` 和 `condition: service_healthy`,应用本身也要有连接重试。
|
||||
|
||||
## 场景题
|
||||
|
||||
### 【场景题】容器启动后马上退出,怎么排查?
|
||||
|
||||
**参考答案**:`docker ps -a` 看退出码,`docker logs <容器>` 看输出。常见原因:主进程是后台进程(容器以前台进程为生命周期)、配置或环境变量缺失导致程序报错退出、二进制和基础镜像不兼容(CGO 程序放进 scratch)、权限问题(非 root 用户无权读文件)。可以用 `docker run -it --entrypoint sh 镜像` 进入容器手动执行排查。
|
||||
|
||||
### 【场景题】应用容器连不上数据库容器,怎么排查?
|
||||
|
||||
**参考答案**:确认连接地址用的是服务名而不是 localhost;两个容器是否在同一网络(`docker network inspect`);数据库是否真的就绪(健康检查、日志);端口是否是容器内端口而不是宿主机映射端口;用户名密码和数据库名是否和初始化时一致(数据卷已存在时环境变量不会重新生效)。
|
||||
|
||||
### 【场景题】怎么避免把密钥打包进镜像?
|
||||
|
||||
**参考答案**:不在 Dockerfile 里写密钥,不把 `.env` 等文件复制进镜像(`.dockerignore` 排除);运行时通过环境变量或密钥管理系统(Kubernetes Secret、云厂商的密钥服务)注入;构建时确实需要的密钥(如私有依赖仓库的 token)用 BuildKit 的 `--secret` 挂载,不会留在镜像层里;镜像推送前用扫描工具检查。
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
id: devops.docker.scenario.compose-dev-env
|
||||
title: 一条命令拉起开发环境:Go API + Python AI 服务 + PostgreSQL + Redis
|
||||
type: scenario
|
||||
domain: devops
|
||||
stack: [docker, go, fastapi, postgresql, redis]
|
||||
tags: [Compose, 开发环境, 多语言, 健康检查, 配置管理]
|
||||
level: intermediate
|
||||
prerequisites: [devops.docker.compose-network-volume]
|
||||
est_hours: 2
|
||||
related: [devops.docker.interview, devops.nginx.index]
|
||||
week: [3, 13, 14]
|
||||
---
|
||||
|
||||
# 一条命令拉起开发环境:Go API + Python AI 服务 + PostgreSQL + Redis
|
||||
|
||||
## 业务背景与问题
|
||||
|
||||
一个企业知识库项目:Go 写业务 API(用户、权限、文档管理),Python FastAPI 写 AI 服务(RAG 检索、调用大模型),PostgreSQL(含 pgvector)存数据和向量,Redis 做缓存。新人入职配环境要一两天:Python 版本不一致、pgvector 扩展装不上、各自本机的端口冲突;测试环境和开发环境配置也对不上。
|
||||
|
||||
## 约束
|
||||
|
||||
- 开发者使用 macOS、Windows(WSL2)、Linux 都有。
|
||||
- 模型 API Key 不能出现在仓库里。
|
||||
- 开发时改代码要能快速生效,不想每次都重新构建镜像。
|
||||
- 同一套编排文件,尽量也能用于单机测试环境。
|
||||
|
||||
## 方案设计
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Dev[浏览器 / 前端 dev server] -->|:8080| GW[Nginx 网关]
|
||||
GW -->|/api| API[Go API]
|
||||
GW -->|/ai| AI[Python AI 服务]
|
||||
API --> DB[(PostgreSQL + pgvector)]
|
||||
AI --> DB
|
||||
API --> R[(Redis)]
|
||||
AI --> R
|
||||
```
|
||||
|
||||
1. **一个 `compose.yaml` 描述全部服务**,服务之间用服务名通信;只有网关映射端口到宿主机。
|
||||
2. **数据库用带 pgvector 的镜像**,初始化 SQL 放在 `./db/init/` 挂载到 `/docker-entrypoint-initdb.d/`(只在数据卷为空的首次启动时执行)。
|
||||
3. **健康检查 + 依赖条件**:数据库健康后才启动 API 和 AI 服务。
|
||||
4. **配置分层**:`compose.yaml` 写公共配置;`compose.override.yaml`(开发时自动合并)挂载源码目录、开启热重载;密钥放在不提交的 `.env`,仓库里提供 `.env.example`。
|
||||
5. **Makefile 封装常用命令**:`make up`、`make logs`、`make psql`、`make reset-db`。
|
||||
|
||||
## 关键代码
|
||||
|
||||
```yaml
|
||||
# compose.yaml(节选)
|
||||
services:
|
||||
gateway:
|
||||
image: nginx:1.27-alpine
|
||||
ports: ["8080:80"]
|
||||
volumes:
|
||||
- ./deploy/nginx.conf:/etc/nginx/conf.d/default.conf:ro
|
||||
depends_on: [api, ai]
|
||||
|
||||
api:
|
||||
build: ./api
|
||||
environment:
|
||||
DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app?sslmode=disable
|
||||
REDIS_URL: redis://redis:6379/0
|
||||
depends_on:
|
||||
db: { condition: service_healthy }
|
||||
|
||||
ai:
|
||||
build: ./ai
|
||||
environment:
|
||||
DATABASE_URL: postgresql://app:${DB_PASSWORD}@db:5432/app
|
||||
LLM_API_KEY: ${LLM_API_KEY} # 来自不提交的 .env
|
||||
depends_on:
|
||||
db: { condition: service_healthy }
|
||||
|
||||
db:
|
||||
image: pgvector/pgvector:pg17
|
||||
environment:
|
||||
POSTGRES_USER: app
|
||||
POSTGRES_PASSWORD: ${DB_PASSWORD}
|
||||
POSTGRES_DB: app
|
||||
volumes:
|
||||
- pgdata:/var/lib/postgresql/data
|
||||
- ./db/init:/docker-entrypoint-initdb.d:ro # 首次启动执行 CREATE EXTENSION vector 等
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U app -d app"]
|
||||
interval: 5s
|
||||
retries: 10
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
|
||||
volumes:
|
||||
pgdata:
|
||||
```
|
||||
|
||||
```yaml
|
||||
# compose.override.yaml:docker compose up 时自动合并,只用于本地开发
|
||||
services:
|
||||
ai:
|
||||
volumes:
|
||||
- ./ai/app:/app/app # 挂载源码
|
||||
command: ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
|
||||
```
|
||||
|
||||
单个 Go 服务的完整 Dockerfile 和 compose 示例见 [examples/go-api-compose](../examples/go-api-compose/)。镜像标签仅作示例,以各镜像的官方页面为准。
|
||||
|
||||
## 取舍
|
||||
|
||||
| 方案 | 优点 | 缺点 |
|
||||
| --- | --- | --- |
|
||||
| **Compose 全部容器化(本方案)** | 环境一致、上手快 | 在 macOS / Windows 上挂载源码的文件性能较差;镜像占磁盘 |
|
||||
| 只把依赖(数据库、Redis)放容器,应用本机跑 | 调试方便、热更新快 | 应用的语言版本仍需各自安装 |
|
||||
| 远程开发环境(云端开发机 / Dev Container) | 环境完全统一 | 需要网络和额外成本 |
|
||||
|
||||
实际团队里常见做法是两者结合:依赖一律容器化;应用代码可以选择容器内运行或本机运行。
|
||||
|
||||
## 易错点
|
||||
|
||||
- 修改了 `db/init` 里的 SQL 却发现没执行:初始化脚本只在数据卷为空时执行,需要 `docker compose down -v` 重建(会清空数据)或写迁移脚本。
|
||||
- `.env` 被提交到仓库,泄露模型 API Key。加入 `.gitignore`,提交前扫描(仓库里的 `tools/check_sensitive.py`)。
|
||||
- 所有服务都映射端口,本机端口冲突;只映射网关。
|
||||
- 开发环境的 `--reload`、源码挂载被带到测试环境:override 文件只用于开发,测试环境显式指定 `-f compose.yaml`。
|
||||
- 容器内时区、字符集和生产不一致,导致时间相关的 bug 只在某个环境出现。统一使用 UTC 存储。
|
||||
|
||||
## 面试怎么讲
|
||||
|
||||
> “项目是 Go 业务 API 加 Python AI 服务,依赖 PostgreSQL(pgvector)和 Redis。我用 Compose 把它们编排起来:服务之间用服务名通信,只有网关对外映射端口;数据库加了健康检查,应用等数据库就绪才启动;密钥放在不提交的 .env,开发时用 override 文件挂载源码热重载。新人 clone 后一条命令就能跑起来。”
|
||||
|
||||
追问准备:生产环境也用 Compose 吗(单机小规模可以,多机用 Kubernetes)?数据怎么备份?
|
||||
Reference in new issue
Block a user