在ubuntu20.04+系统部署VUE及Django项目的过程记录——以腾讯云为例

1. 需求

近期做一些简单工程开发基本都采用的VUE-Django框架，需要部署在单位服务器或腾讯云服务器，步骤稍微有些杂，容易忘，每次都得问LLM，故做此记录，以供参考。

2. 项目准备

如何创建VUE及Django项目，此博客不做阐述。

3. VUE CLI项目部署

3.1 部署前的准备

将本地写的vue cli项目整个打包到服务器。

3.1.1 后端通信路由修改

我这里用的是VUE CLI。在.vue文件中，若有前后段数据传输或函数调用，一定记得在script中把路由该一下，不能是本地的127.0.0.1，若服务器地址是43.***.**.63，则需要换成这个地址,最好直接用域名。
例如：

const response = await fetch('http://127.0.0.1:8000/api/journal/');

就需要改为：

const response = await fetch('https://i...s.cn/api/journal/');

8000 被移除，因为 Nginx 通常会配置为监听 80 (HTTP) 或 443 (HTTPS) 端口，并将请求代理到后端的 8000 端口。如果你的服务器配置了 HTTPS，应使用 https://。
可以导航到相应的目录下，执行以下代码查看哪些文件包含127.0.0.1

grep -rl '127.0.0.1' .

如果使用诸如const response = await axios.get('/api/email/history')就不会有这个问题。

3.1.2 导航修改

找到vue cli项目根目录下的vue.config.js文件，如下：

const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({transpileDependencies: true,devServer: {port: 8080},// 新增：配置 htmlWebpackPlugin 的选项chainWebpack: config => {config.plugin('html').tap(args => {args[0].title = '标题'; // 设置网页标题return args;});},publicPath: '/xb/' // 添加这一行
})

需要新增 publicPath: '/xb/'

找到文件/src/router/index.js，底部添加：

const router = createRouter({history: createWebHistory('/xb/'),routes
})

找到文件src/main.js
找到设置 Axios baseURL 的行:
查找类似 axios.defaults.baseURL = 'http://43.×××.××.63' 的代码。
修改为正确的 HTTPS 地址和域名:

// 推荐使用域名并确保协议是 https
axios.defaults.baseURL = 'https://i...s.cn'

执行npm run build.

3.2 构建项目

在VUE CLI目录下执行npm run build构建项目，会生成dist目录。

3.3 配置nginx代理

在路径/etc/nginx/sites-available下新建一个配置文件，如果不新建可以都写在default中，但太多容易乱。更推荐新建一个。
比如，我新建了一个i...s.cn（我的域名），然后写入配置：

# HTTP Redirect for i...s.cn
server {listen 80;listen [::]:80;server_name i...s.cn www.i...s.cn;return 301 https://$host$request_uri;
}# HTTPS Configuration for i...s.cn
server {listen 443 ssl http2;listen [::]:443 ssl http2;server_name i...s.cn www.i...s.cn;ssl_certificate /www/server/panel/vhost/cert/i...s.cn/fullchain.pem;ssl_certificate_key /www/server/panel/vhost/cert/i...s.cn/privkey.pem;# 1. i...s.cn 官方网站根目录root /www/wwwroot/i...s.cn;index index.html index.htm index.php;# 2. pdf_download 配置(在该域名下的其他目录网站)location /pdf_download/ {alias /www/wwwroot/i...s.cn/pdf_download/;index dashboard.html;autoindex off;}# 3. vue 应用配置 (部署在 /xb/ 路径下)location /xuebao/ {alias /www/wwwroot/i...s.cn/xb/vue/dist/;index index.html index.htm;try_files $uri $uri/ /xb/index.html;}# 处理官方网站根路径和其他未匹配的路径location / {try_files $uri $uri/ /index.php?$args;}# 处理 PHP 文件请求 (如果官方网站需要)location ~ \.php$ {include snippets/fastcgi-php.conf;fastcgi_pass unix:/tmp/php-cgi-80.sock; # 请确认此路径是否正确fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;include fastcgi_params;}# 访问和错误日志access_log /var/log/nginx/i...s.cn.access.log;error_log /var/log/nginx/i...s.cn.error.log;
}
}

因为是新建的配置文件，需要执行
sudo ln -s /etc/nginx/sites-available/i...s.cn /etc/nginx/sites-enabled/i...s.cn
以及重启nginx
sudo nginx -t、sudo systemctl reload nginx
重启之后，访问相应URL，前端页面显示正常。
若要关闭nginx服务，执行sudo systemctl stop nginx

4. 后端配置

这里后端采用的是django，django环境安装不再赘述。
这里需要注意，在正式配置后端之前，一定要在django项目的settings.py中修改以下配置：

1. DEBUG = False
2. ALLOWED_HOSTS添加自己的域名

4.1 其他依赖项

这里的HTTP服务器我选择Gunicorn。
若没有执行pip install gunicorn

4.2 单次执行测试

可先单独执行django，确保没有因为环境问题造成的bug。
切换到django目录下，执行gunicorn --bind 127.0.0.1:8000 qk.wsgi:application
看到类似以下信息，则没有问题：

gunicorn --bind 127.0.0.1:8000 qk.wsgi:application
[2025-04-16 22:02:35 +0800] [2812697] [INFO] Starting gunicorn 23.0.0
[2025-04-16 22:02:35 +0800] [2812697] [INFO] Listening at: http://127.0.0.1:8000 (2812697)
[2025-04-16 22:02:35 +0800] [2812697] [INFO] Using worker: sync
[2025-04-16 22:02:35 +0800] [2812698] [INFO] Booting worker with pid: 2812698

ctrl+c停止手动运行的Gunicorn。

4.3 创建Systemd 服务文件

这是让 Django (通过 Gunicorn) 在后台运行、开机自启、并在失败时自动重启的关键。

sudo nano /etc/systemd/system/自定义命名.service

粘贴配置以下内容

[Unit]
Description=gunicorn daemon for qk Django project
After=network.target # 表示在网络可用后启动[Service]
# === 修改为你运行代码的用户和组 ===
User=ubuntu  # 创建的专用用户
Group=ubuntu # 用户同名组# === 修改为你的 Django 项目根目录 ===
WorkingDirectory=/www/wwwroot/....# === 修改为你的 Python 环境中 gunicorn 和 python 的绝对路径 ===
ExecStart=/home/ubuntu/anaconda3/envs/ser/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 qk.wsgi:application \--access-logfile /var/log/gunicorn/gunicorn-qk-access.log \--error-logfile /var/log/gunicorn/gunicorn-qk-error.logRestart=always          # 如果服务退出，总是尝试重启
RestartSec=10           # 重启前等待 10 秒
KillSignal=SIGQUIT      # 使用 SIGQUIT 平滑关闭 Gunicorn
TimeoutStopSec=5        # 等待 5 秒后强制关闭
PrivateTmp=true         # 使用私有临时目录[Install]
WantedBy=multi-user.target # 表示服务应该在多用户模式下启用

！！注意，不要有行末注释，我这里是为了解释，配置文件删掉#，不然后续会报错！！
User / Group: 运行 Gunicorn 进程的用户和组。非常重要！ 确保这个用户对项目目录 (WorkingDirectory) 和虚拟环境有读取权限，并且对日志目录 (如果使用) 有写入权限。ubuntu 和 www-data 是常见的选择，但最好使用权限受限的专用用户。
修改好配置文件之后，执行:

1. 重新加载 Systemd 配置: 让 Systemd 读取你新创建的服务文件。sudo systemctl daemon-reload
2. 启动Gunicorn服务：sudo systemctl start 自定义.service
3. 检查服务状态：sudo systemctl status gunicorn-qk.service
   若出现Active: active (running) since Wed 2025-04-16 22:16:16 CST; 28s ago即为成功
   如果失败，可检查日志错误信息。sudo journalctl -u gunicorn-qk.service -n 50 --no-pager
4. 设置开机自启动sudo systemctl enable gunicorn-qk.service

4.4 配置 Nginx 作为反向代理

Django 需要写进 Nginx 的配置文件。Gunicorn 服务正在监听 127.0.0.1:8000，这个地址只能从服务器内部访问。 VUE 前端通过公网 IP 发送请求。Nginx 需要知道：当收到指向 /api/ 的请求时，应该将这个请求转发给内部运行在 127.0.0.1:8000 的 Gunicorn 服务。
需要在/etc/nginx/sites-available/i...s.cn文件的 server { … } 块（监听 443 端口的那个）中添加或修改一个 location /api/ { … } 块。

    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;}

5. 其他注意事项

1. 关于嵌套/嵌入式前端应用部署
   • 问题：当一个预构建的前端应用（应用 B）被嵌入到另一个前端应用（应用 A）的子目录下时，应用 B 内部引用的静态资源（JS, CSS）路径可能因部署路径改变而失效 (404)。
   • 解决：必须为嵌入的应用（应用 B）在其构建配置中明确指定最终的、绝对的部署路径（例如，如果应用 A 在 /app-a/，应用 B 在其下，则路径为 /app-a/app-b/），然后重新构建应用 B。将新构建的产物替换应用 A 中的旧版本（public中），并（如果需要）重新构建应用 A。
2. 关于前端 API 请求 URL
   • 问题：在 HTTPS 页面中硬编码使用 HTTP 协议或 IP 地址的 API 请求 URL，会导致 “Mixed Content” 安全错误或请求失败。直接在组件中写死 URL 也容易出错且不利于维护。
   • 解决：确保所有 API 请求均使用正确的协议 (通常是 HTTPS) 和主机名 (域名)。最佳实践是配置并统一使用一个全局 HTTP 请求库实例（如 Axios），为其设置正确的 baseURL (包含协议和域名)，然后在组件代码中仅使用相对路径（如 /api/data）发起请求。
3. 如何更新服务（在修改代码后）：
   • 后端 (Django/Gunicorn): 修改 Python 代码 (如 views.py, models.py, settings.py) 后，重启 Gunicorn 服务：sudo systemctl restart gunicorn-qk.service,gunicorn-qk.service是自定义的名字。
   • 前端 (VUE): 修改前端源代码 (如 .vue, .js, .css) 后，需要重新构建项目，并将新生成的 dist 文件部署：npm run build
     (Nginx 通常不需要重启或重新加载，因为它会自动提供 dist 目录下的新文件。只有在修改 Nginx 配置文件本身时才需要 sudo systemctl reload nginx)
4. 查看日志命令

   • 后端 (Django/Gunicorn):查看 Gunicorn 错误日志 (主要看 Python/Django 错误):

     sudo tail -n 50 /var/log/gunicorn/gunicorn-qk-error.log
     # 实时查看: sudo tail -f /var/log/gunicorn/gunicorn-qk-error.log
     

   • 查看 Gunicorn 访问日志 (看哪些请求到了后端):

     sudo tail -n 50 /var/log/gunicorn/gunicorn-qk-access.log
     # 实时查看: sudo tail -f /var/log/gunicorn/gunicorn-qk-access.log
     

   • 查看 Systemd 服务日志 (看服务启动/停止状态):

     sudo journalctl -u gunicorn-qk.service -n 50 --no-pager
     # 实时查看: sudo journalctl -u gunicorn-qk.service -f
     

   • 前端 (VUE / Nginx):查看 VUE 运行时错误 (JS 错误): 在浏览器开发者工具 (F12) 的 “Console” (控制台) 查看。查看 Nginx 错误日志 (Nginx 配置、权限错误):

     sudo tail -n 50 /var/log/nginx/insightlens.cn.error.log
     # 实时查看: sudo tail -f /var/log/nginx/insightlens.cn.error.log
     

   • 查看 Nginx 访问日志 (看浏览器请求记录，包括静态文件和 API 代理):

     sudo tail -n 50 /var/log/nginx/insightlens.cn.access.log
     # 实时查看: sudo tail -f /var/log/nginx/insightlens.cn.access.log
     

5. 取消systemctl自启动：
   关闭自启动：sudo systemctl disable gunicorn-qk.service
   停止当前服务并防止它因被 kill 而重启:
   不要直接用 kill 命令。应该使用 systemd 的命令来停止它：
   sudo systemctl stop gunicorn-qk.service