taiyi/xiangqinxiaochengxu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
a8e6edf296
xiangqinxiaochengxu/后台前端与后端系统从零到一上线教程.md
taiyi 6643b14a2f 第一版本提交
2026-05-16 19:01:44 +08:00

12 KiB
Raw Blame History

后台前端与后端系统从零到一上线教程

本文档适用于当前项目：

  • 后端：backend/，FastAPI
  • 后台前端：admin-web/，Vue 3 + Vite
  • 域名：ghxiangqin.com
  • 对外接口地址：https://ghxiangqin.com/api/v1

目标效果：

  • 访问 https://ghxiangqin.com/ 打开后台管理系统
  • 访问 https://ghxiangqin.com/api/v1/... 调用后端接口
  • 外网只开放 80 和 443
  • backend 只在服务器本机监听 127.0.0.1:8000

1. 上线方案总览

这套项目推荐按下面方式部署：

  1. admin-web 不长期跑 npm run dev
  2. admin-web 执行 npm run build，生成静态文件
  3. 静态文件交给 Nginx 直接托管
  4. backend 用 uvicorn 跑在本机端口 127.0.0.1:8000
  5. 宝塔/Nginx 对外只暴露一个站点域名 ghxiangqin.com
  6. Nginx 负责把 /api/ 请求转发到 backend

最后的访问关系如下：

  • https://ghxiangqin.com/ -> 后台前端静态页面
  • https://ghxiangqin.com/api/v1/* -> FastAPI 后端
  • https://ghxiangqin.com/health -> 后端健康检查

2. 服务器准备

建议服务器环境：

  1. Linux 服务器一台
  2. 已安装宝塔面板
  3. 已安装 Nginx
  4. 已安装 MySQL 8
  5. 已安装 Redis
  6. 已安装 Python 3.10 或更高版本
  7. 已安装 Node.js 18 或更高版本

还需要提前准备：

  1. 域名 ghxiangqin.com
  2. 域名 A 记录解析到服务器公网 IP
  3. 服务器安全组/防火墙放行 80、443

3. 上传项目代码

把整个项目上传到服务器，比如：

/www/wwwroot/xqxcx

建议最终目录结构如下：

/www/wwwroot/xqxcx/
├─ admin-web/
├─ backend/
├─ miniprogram/
└─ 其它文档

4. 创建数据库

登录 MySQL，执行：

CREATE DATABASE dating_app DEFAULT CHARACTER SET utf8mb4;

如果数据库名不是 dating_app，后面 .env 里要同步改。

5. 配置后端环境变量

进入后端目录：

cd /www/wwwroot/xqxcx/backend

复制环境变量模板：

cp .env.example .env

然后编辑 .env，至少改这些值：

APP_NAME=dating-mini-program-api
APP_ENV=production
APP_DEBUG=false
API_V1_PREFIX=/api/v1

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=你的数据库密码
MYSQL_DATABASE=dating_app

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=

JWT_SECRET_KEY=换成一串复杂随机字符串
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=10080

WX_APPID=你的小程序APPID
WX_SECRET=你的小程序SECRET

COS_REGION=你的腾讯云COS地域
COS_SECRET_ID=你的COS_SECRET_ID
COS_SECRET_KEY=你的COS_SECRET_KEY
COS_BUCKET=你的COS桶名
COS_BASE_URL=你的COS访问地址

WX_TEMPLATE_AUDIT_RESULT=审核结果模板ID
WX_TEMPLATE_MATCH_SUCCESS=匹配成功模板ID

注意：

  1. APP_DEBUG 上线必须改成 false
  2. JWT_SECRET_KEY 不要继续用默认值
  3. 如果 Redis 没设密码，REDIS_PASSWORD 可以留空

6. 安装后端依赖

仍在 backend/ 目录执行：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

如果服务器命令是 python，就把 python3 改成 python。

7. 执行数据库迁移

在 backend/ 目录执行：

source .venv/bin/activate
alembic upgrade head

成功后，数据库里会生成项目需要的数据表。

8. 初始化后台管理员账号

在 backend/ 目录执行：

source .venv/bin/activate
python scripts/init_admin.py

初始化后，后台默认管理员一般可用：

  • 用户名：admin
  • 密码：以脚本实际输出或项目默认说明为准

首次登录后建议立刻改密码。

9. 启动后端服务

9.1 临时启动测试

先手动启动确认能跑：

cd /www/wwwroot/xqxcx/backend
source .venv/bin/activate
uvicorn main:app --host 127.0.0.1 --port 8000

然后本机检查：

curl http://127.0.0.1:8000/health

正常应返回：

{"status":"ok"}

9.2 正式常驻启动

生产环境建议用宝塔的 Python 项目管理器、Supervisor，或 systemd 来托管进程。
如果你用宝塔的 Supervisor，命令可填：

cd /www/wwwroot/xqxcx/backend && /www/wwwroot/xqxcx/backend/.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000

关键点：

  1. 只监听 127.0.0.1
  2. 不要直接暴露 8000 给公网
  3. 对外统一走 Nginx 反向代理

10. 打包后台前端

进入前端目录：

cd /www/wwwroot/xqxcx/admin-web

安装依赖：

npm install

执行打包：

npm run build

打包完成后会生成：

admin-web/dist/

说明：

  1. dist/ 里是纯静态文件
  2. 不需要再运行 npm run dev
  3. 不需要给前端单独开端口

11. 创建宝塔站点

在宝塔面板里创建站点：

  1. 域名填：ghxiangqin.com
  2. 如果需要，也加上：www.ghxiangqin.com
  3. PHP 版本选“纯静态”或不启用 PHP
  4. 网站目录建议设为：
/www/wwwroot/ghxiangqin.com

创建完成后，把 admin-web/dist/ 里的所有文件复制到这个目录：

/www/wwwroot/ghxiangqin.com

注意是复制 dist 目录中的内容，不是把 dist 整个目录原样套进去。

最终应该像这样：

/www/wwwroot/ghxiangqin.com/index.html
/www/wwwroot/ghxiangqin.com/assets/...

12. 配置 Nginx 反向代理

12.1 未配置 SSL 证书前的可用版

如果你还没申请 HTTPS 证书，先用下面配置：

server {
    listen 80;
    server_name ghxiangqin.com www.ghxiangqin.com;

    root /www/wwwroot/ghxiangqin.com;
    index index.html index.htm;

    client_max_body_size 20m;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /health {
        proxy_pass http://127.0.0.1:8000/health;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

12.2 配置 SSL 证书后的正式版

在宝塔站点中先申请 Let's Encrypt 证书，成功后再用 HTTPS 配置。
如果证书由宝塔自动配置，通常只需要保留宝塔生成的证书路径，再加上下面的 location 即可。

示例正式版：

server {
    listen 80;
    server_name ghxiangqin.com www.ghxiangqin.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name ghxiangqin.com www.ghxiangqin.com;

    ssl_certificate /www/server/panel/vhost/cert/ghxiangqin.com/fullchain.pem;
    ssl_certificate_key /www/server/panel/vhost/cert/ghxiangqin.com/privkey.pem;

    root /www/wwwroot/ghxiangqin.com;
    index index.html index.htm;

    client_max_body_size 20m;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /health {
        proxy_pass http://127.0.0.1:8000/health;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

说明：

  1. / 用于托管后台前端静态页面
  2. /api/ 反代到 FastAPI
  3. try_files ... /index.html 是为了支持 Vue 路由刷新
  4. client_max_body_size 20m 是为了后续上传图片时不被拦截

13. 申请 SSL 证书

微信小程序正式环境要求接口必须是 HTTPS，所以上线最终一定要配置证书。

宝塔操作步骤：

  1. 打开站点 ghxiangqin.com
  2. 进入 SSL
  3. 选择 Let's Encrypt
  4. 申请证书
  5. 申请成功后启用证书
  6. 按需开启“强制 HTTPS”

如果 Nginx 保存时报：

no "ssl_certificate" is defined for the "listen ... ssl" directive

说明你先写了 listen 443 ssl，但证书还没配好。
这时先用“未配置 SSL 证书前的可用版”，不要先写 443 ssl。

14. 检查后台前端和后端联通

先确认以下地址是否正常：

  1. 后端健康检查
    https://ghxiangqin.com/health

  2. 后端公开配置
    https://ghxiangqin.com/api/v1/auth/public-config

  3. 后台首页
    https://ghxiangqin.com/

如果后台登录页能打开，但登录失败，重点检查：

  1. backend 进程是否真的在运行
  2. Nginx /api/ 反向代理是否生效
  3. MySQL 是否可连接
  4. 管理员账号是否初始化完成

15. 小程序侧需要同步的配置

当前代码默认接口地址已经切到：

https://ghxiangqin.com/api/v1

但微信公众平台还需要额外配置合法域名。

需要在微信公众平台配置：

  1. request 合法域名 添加
    https://ghxiangqin.com

  2. 如果图片走你自己的域名，也要把图片域名加入合法域名

如果没配置，真机或正式版会报：

request:fail url not in domain list

16. 后台前端更新流程

以后后台前端改了代码，更新方式如下：

cd /www/wwwroot/xqxcx/admin-web
npm install
npm run build

然后把新的 dist/ 内容覆盖到：

/www/wwwroot/ghxiangqin.com/

一般不需要重启 Nginx。

17. 后端更新流程

以后后端改了代码，更新方式如下：

cd /www/wwwroot/xqxcx/backend
source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head

然后重启后端进程管理器中的服务，例如：

  1. 宝塔 Python 项目
  2. Supervisor
  3. systemd

18. 常见问题排查

18.1 首页能打开，但接口 404

说明前端静态站点正常，但 /api/ 反代没有生效。
重点检查 Nginx 里是否有：

location /api/ {
    proxy_pass http://127.0.0.1:8000;
}

18.2 接口 502 Bad Gateway

说明 Nginx 找不到后端。
检查：

  1. uvicorn 是否运行中
  2. 是否监听在 127.0.0.1:8000
  3. 宝塔反代目标地址是否写对

18.3 刷新后台子页面 404

说明 Vue 路由回退没配好。
确保 Nginx 有：

location / {
    try_files $uri $uri/ /index.html;
}

18.4 宝塔保存 Nginx 失败

如果错误里提到 SSL 证书缺失，就说明证书还没配置好。
先删掉：

listen 443 ssl http2;

等证书申请完成后再启用 HTTPS 配置。

18.5 小程序请求失败

检查：

  1. https://ghxiangqin.com/api/v1/auth/public-config 是否可访问
  2. 微信后台是否配置合法域名
  3. SSL 证书是否有效
  4. 是否被防火墙拦截

19. 推荐的最终部署结构

推荐结构如下：

/www/wwwroot/
├─ xqxcx/
│  ├─ backend/
│  ├─ admin-web/
│  └─ miniprogram/
└─ ghxiangqin.com/
   ├─ index.html
   └─ assets/

说明：

  1. 源码放在 xqxcx/
  2. 前端打包结果单独放在站点目录 ghxiangqin.com/
  3. Nginx 直接托管站点目录
  4. 后端继续从源码目录运行

20. 一次完整上线的最短操作清单

按顺序执行：

  1. 上传项目到服务器
  2. 创建 MySQL 数据库 dating_app
  3. 配置 backend/.env
  4. 创建后端虚拟环境并安装依赖
  5. 执行 alembic upgrade head
  6. 执行 python scripts/init_admin.py
  7. 启动 backend 到 127.0.0.1:8000
  8. 执行 admin-web/npm install
  9. 执行 admin-web/npm run build
  10. 把 dist/ 内容复制到 /www/wwwroot/ghxiangqin.com/
  11. 在宝塔站点配置 Nginx：/ 静态站点，/api/ 反代后端
  12. 访问 http://ghxiangqin.com/health 检查后端
  13. 访问 http://ghxiangqin.com/ 检查后台
  14. 申请 SSL 证书
  15. 切换到 HTTPS
  16. 在微信公众平台配置 https://ghxiangqin.com 为合法域名

21. 本项目当前已经确认的地址

当前项目中已经统一使用：

后台前端默认接口地址：
https://ghxiangqin.com/api/v1

小程序默认接口地址：
https://ghxiangqin.com/api/v1

所以只要 Nginx 的 /api/ 反代配置正确，前后端就能直接连通。