>服务器：Ubuntu 22.04 LTS ，目标：用 Docker Compose 跑通一个 Next.js 前端 + FastAPI 后端 + PostgreSQL 数据库的全栈项目

大家好，我是码农刚子。这篇记录一下我在 Ubuntu 22.04 上从零开始安装 Docker、配置国内镜像源、编写 `docker-compose.prod.yml`，最终把一个全栈项目跑上线的完整过程。如果你也在用国内网络环境部署，应该能避开不少我踩过的坑。
## 一、安装 Docker 与 Docker Compose

Ubuntu 22.04 默认源里的 `docker.io` 虽然能装，但 `docker-compose-plugin` 经常找不到。建议直接换阿某云或官方源：
```
# 安装基础依赖
apt update && apt install -y ca-certificates curl gnupg lsb-release

# 添加 Docker 官方 GPG 与源（国内推荐阿某云镜像）
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://mirrors.aliyun.com/docker-ce/linux/ubuntu \
  $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list

# 安装
deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu jammy stable
apt update && apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```
装完后验证：
```
docker --version          # Docker version 24.x
docker compose version    # v2.x
```
![安装 Docker 与 Docker Compose](https://developer.qcloudimg.com/http-save/yehe-11675143/16f5e6a38cce2bd47396a9b592e094f7.png)
## 二、配置国内 Docker 镜像加速器

国内直接拉 `docker.io` 很容易超时，必须配加速器。我踩了腾讯、163、阿某云专属加速器几个坑，最后 **DaoCloud 公共加速器** 最稳：
```
mkdir -p /etc/docker
cat > /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}
EOF
systemctl daemon-reload && systemctl restart docker
```
>注意：`registry-mirrors` 地址末尾**不要加斜杠**，否则可能报 403。

## 三、项目结构与生产配置

项目根目录 `/opt/eduai` 结构：
```
/opt/eduai
├── backend/              # FastAPI
├── frontend/             # Next.js
├── docker-compose.prod.yml
├── .env.prod
└── deploy/nginx.conf
```
生产 `docker-compose.prod.yml` 核心要点：
- API 去掉 `--reload`，加 `--workers 4`；
- Web/Api 只绑 `127.0.0.1`，避免直接暴露；
- 用 `${VAR:?}` 强制必填环境变量；
- PostgreSQL 数据持久化到命名卷。

```
services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: ${POSTGRES_DB:?}
      POSTGRES_USER: ${POSTGRES_USER:?}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?}
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - backend

  api:
    build: ./backend
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
    env_file: .env.prod
    depends_on:
      - postgres
    networks:
      - backend

  web:
    build: ./frontend
    env_file: .env.prod
    depends_on:
      - api
    networks:
      - backend

  nginx:
    image: nginx:1.18-alpine
    ports:
      - "80:80"
    volumes:
      - ./deploy/nginx.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - api
      - web
    networks:
      - backend

volumes:
  pgdata:

networks:
  backend:
```
## 四、Dockerfile 国内源

后端 `backend/Dockerfile` 加清华 pip 源：
```
ARG PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
ENV PIP_TRUSTED_HOST=pypi.tuna.tsinghua.edu.cn
```
前端 `frontend/Dockerfile` 加淘宝 npm 源：
```
ENV npm_config_registry=https://registry.npmmirror.com
```
这三件套（DaoCloud + 清华 pip + 淘宝 npm）基本能覆盖国内大部分镜像拉取和包安装场景。
## 五、启动与验证

```
cd /opt/eduai
docker compose -f docker-compose.prod.yml up -d --build
```
等 20 秒左右，容器冷启动完成后验证：
```
docker compose ps
curl -s http://127.0.0.1:8000/health
```
正常应返回：
```
{"status":"ok","env":"prod"}
```
## 六、踩坑总结

|现象|原因|解决|
|:-:|:-:|:-:|
|`Unable to locate package docker-compose-plugin`|默认源没这个包|换阿里云 Docker CE 源|
|拉镜像 `i/o timeout`|docker.io 被墙/慢|配 DaoCloud 镜像加速器|
|pip/npm install 超时|境外源|Dockerfile 里加清华/淘宝源|
|`COPY /app/public not found`|Next.js standalone 需要 public 目录|建 `frontend/public/.gitkeep`|
|`/health` 一开始空响应|API 冷启动慢|等 20 秒或加健康检查重试|
|时区 aware/naive 报错|PostgreSQL 列是 naive，代码写 aware|统一用 `datetime.utcnow()` 或落库前 `replace(tzinfo=None)`|
## 七、小结

在 **某免费云服务器** 上跑 Ubuntu 22.04 + Docker Compose 完全可行。只要提前做好「国内源三件套」配置，大部分网络问题都能避免。这套部署方式后续也方便迁移到任何支持 Docker 的付费主机上。
如果大家对 Dockerfile、Compose 文件或 nginx 反向代理配置感兴趣，可以在评论区留言，我把完整文件贴出来。

----
**关于作者**
码农刚子，六年 ERP / 制造业系统开发，专注 C# / .NET / Blazor。 写 PCB 行业 ERP 与多租户 SaaS 的实战与踩坑，不写面试八股。
博客：https://www.coderlog.net/

服务器：Ubuntu 22.04 LTS ，目标：用 Docker Compose 跑通一个 Next.js 前端 + FastAPI 后端 + PostgreSQL 数据库的全栈项目

Ubuntu 22.04 Docker 从零部署全栈项目实录：Next.js + FastAPI + PostgreSQL 一次跑通

服务器：阿贝云免费云服务器 / Ubuntu 22.04 LTS 目标：用 Docker Compose 跑通一个 Next.js 前端 + FastAPI 后端 + PostgreSQL 数据库的全栈项目

全栈软件工程师

Ubuntu22.04上通过Docker Compose部署Next.js+FastAPI+PostgreSQL全栈项目，配置国内源三件套（DaoCloud镜像加速、清华pip源、淘宝npm源）解决网络问题，实现生产环境快速上线，含完整部署步骤与踩坑指南。

代码解释

云服务器

SQL数据库

PostgreSQL

服务器

数据库

Docker

容器

SaaS

2026上云采购 | AI焕新·智启新局

postgres

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Ubuntu 22.04 Docker 从零部署全栈项目实录：Next.js + FastAPI + PostgreSQL 一次跑通-腾讯云开发者社区-腾讯云

Ubuntu 22.04 Docker 从零部署全栈项目实录：Next.js + FastAPI + PostgreSQL 一次跑通

Ubuntu 22.04 Docker 从零部署全栈项目实录：Next.js + FastAPI + PostgreSQL 一次跑通

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐