前端步入全栈第一步

🚀 基于腾讯云 Docker 部署 Vue3 + FastAPI + PostgreSQL 全栈应用：从零到上线完整指南

作者 ：[你的昵称]
部署平台 ：腾讯云轻量应用服务器（Ubuntu 22.04）
技术栈：

• 前端：Vue3 + Vite
• 后端：FastAPI（Python 3.10+）
• 数据库：PostgreSQL 15
• 容器编排：Docker Compose
  目标：实现一键部署、数据持久化、安全运维

---

一、为什么选择这套组合？

• FastAPI：高性能、自动生成 API 文档（Swagger / ReDoc），异步支持优秀
• PostgreSQL：功能强大、开源可靠，适合结构化数据存储
• Docker Compose：本地开发与生产部署一致，环境隔离无冲突
• 腾讯云轻量服务器：性价比高，适合个人项目/小团队快速上线

---

二、服务器准备（腾讯云）

1. 创建轻量应用服务器

• 镜像：Ubuntu 22.04 LTS
• 规格：2核4G（起步足够）
• 安全组开放端口：80（HTTP）、443（HTTPS）、22（SSH）

🔒 重要 ：不要开放 5432（PostgreSQL）端口！数据库仅限内网访问。

2. 安装 Docker 与 Docker Compose

bash

编辑

# 安装 Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# 安装 Docker Compose（v2+）
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 重新登录或执行
newgrp docker

验证：

bash

编辑

docker --version        # Docker version 24.x
docker-compose version  # v2.x

---

三、项目目录结构

text

编辑

note-app/
├── backend/            # FastAPI 项目
│   ├── main.py
│   ├── models.py
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/           # Vue3 项目
│   ├── vite.config.js
│   └── Dockerfile
└── docker-compose.yml

---

四、FastAPI 后端关键配置

1. backend/main.py（示例）

python

编辑

from fastapi import FastAPI
from sqlalchemy import create_engine

app = FastAPI()

# 从环境变量读取 DATABASE_URL
import os
DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///./test.db")

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

✅ 务必通过环境变量注入 DATABASE_URL，不要硬编码！

2. backend/requirements.txt

txt

编辑

fastapi==0.110.0
uvicorn[standard]==0.27.1
sqlalchemy==2.0.25
psycopg2-binary==2.9.9
python-dotenv  # 可选

3. backend/Dockerfile

dockerfile

编辑

FROM python:3.10-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

COPY . .

# 暴露端口（容器内部）
EXPOSE 8000

# 启动命令：监听 0.0.0.0（关键！）
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

⚠️ 必须监听 0.0.0.0，否则 Docker 外部无法访问！

---

五、前端 Vue3 构建（Nginx 托管）

frontend/Dockerfile

dockerfile

编辑

# 构建阶段
FROM node:18 AS build
WORKDIR /app
COPY . .
RUN npm install && npm run build

# 运行阶段
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

---

六、docker-compose.yml（核心配置）

yaml

编辑

version: '3.8'

services:
  # PostgreSQL 数据库
  db:
    image: postgres:15
    container_name: note-db
    restart: always
    environment:
      POSTGRES_USER: noteuser
      POSTGRES_PASSWORD: notepass
      POSTGRES_DB: notedb
    volumes:
      - pgdata:/var/lib/postgresql/data  # 持久化数据
    networks:
      - app-net
    # 注意：不暴露 5432 端口！

  # FastAPI 后端
  backend:
    build: ./backend
    container_name: note-backend
    depends_on:
      - db
    ports:
      - "8000:8000"   # 映射 API 端口
    environment:
      - DATABASE_URL=postgresql://noteuser:notepass@db:5432/notedb
    networks:
      - app-net

  # Vue3 前端（Nginx）
  frontend:
    build: ./frontend
    container_name: note-frontend
    ports:
      - "80:80"
    restart: unless-stopped
    networks:
      - app-net

volumes:
  pgdata:  # 命名卷，用于数据库持久化

networks:
  app-net:
    driver: bridge

---

七、部署流程

bash

编辑

# 1. 上传项目到服务器
scp -r . ubuntu@<你的服务器IP>:/home/ubuntu/note-app

# 2. 登录服务器
ssh ubuntu@<你的服务器IP>

# 3. 启动服务
cd note-app
docker-compose up -d --build

# 4. 查看日志
docker-compose logs -f backend

✅ 访问 http://<你的服务器IP> 即可看到前端

✅ 访问 http://<你的服务器IP>:8000/docs 查看 FastAPI 自动生成的 Swagger 文档

---

八、如何安全查看 PostgreSQL 数据？

❌ 错误做法：直接操作宿主机上的数据库文件 → 极易损坏数据！

✅ 推荐方式 1：容器内使用 psql

bash

编辑

docker exec -it note-db psql -U noteuser -d notedb

✅ 推荐方式 2：Navicat 通过 SSH 隧道 连接（安全！）

Navicat 配置：

选项卡	设置
常规	主机：127.0.0.1，端口：5432，用户名：noteuser，密码：notepass
SSH	✅ 启用 SSH 隧道 主机：你的腾讯云公网IP 端口：22 用户名：ubuntu 认证方法：密码 或 私钥

✅ 无需开放 5432 端口，安全又方便！

---

九、高频易错点 & 解决方案

问题	原因	解决方案
FastAPI 启动后外部无法访问	未监听 0.0.0.0	uvicorn --host 0.0.0.0
后端连不上 PostgreSQL	DATABASE_URL 中 host 写成 localhost	必须用服务名 db
数据库重启后数据丢失	未配置 volumes	确保使用命名卷 pgdata
前端请求后端跨域（CORS）	FastAPI 未启用 CORS	安装 fastapi.middleware.cors 并配置
构建慢 / 超时	pip 默认源在国外	在 Dockerfile 中使用清华源
中文乱码	PostgreSQL 编码问题	postgres:15 默认 UTF-8，一般无需处理

💡 FastAPI CORS 示例：

python

编辑

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 生产环境应限制为具体域名
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

---

十、生产环境安全加固建议

1. 禁止暴露数据库端口（5432）

2. 使用 .env 文件管理敏感信息（配合 python-dotenv）

3. 为前端配置 HTTPS（可用 Nginx + Let's Encrypt）

4. 定期备份数据库：

   bash

   编辑

   docker exec note-db pg_dump -U noteuser notedb > backup_$(date +%F).sql

5. 限制容器资源（在 docker-compose.yml 中添加 deploy.resources）

6. 更新依赖，定期扫描漏洞（如 pip-audit）

---

十一、总结

通过本文的配置，你可以：

• ✅ 在腾讯云上一键部署 Vue3 + FastAPI + PostgreSQL 应用
• ✅ 实现数据库持久化，避免数据丢失
• ✅ 安全地通过 Navicat 管理数据库（SSH 隧道）
• ✅ 规避常见部署陷阱，提升上线效率