云服务器上部署单项目/多项目

简单"说几句"

最近整了个2核2G的轻量云服务器，别问，问就是穷学生套餐。趁着这功夫，把本地肝了的项目怼到云服务器上，顺便踩了一堆坑，于是又肝出这篇部署笔记。

说实话，一开始我对服务器部署的认知还停留在"把文件拖进去稍微配置就能跑"的阶段，结果现实给我当头一棒------端口冲突、权限报错、环境变量读不到、构建到一半 Xshell 断连......各种玄学问题轮番上阵，差点让我把电脑打飞。

这篇笔记主要记录单项目部署 和多项目共存 的完整流程，工具用的是Xshell + Xftp + Docker，主打一个"配置一次，复制粘贴到处用"。如果你也是第一次搞服务器部署，或者服务器配置跟我一样寒酸（2G 内存瑟瑟发抖），那这篇应该能帮到你。废话不多说，直接上干货。

这里我用的Xshell+Xftp+docker进行部署

1.XShell

简单说明：

Xshell 是一款功能强大的终端模拟软件，用于安全远程连接和管理服务器，支持多种协议和高级会话管理功能。

第一步：输入服务器IP并连接

服务器IP去你所购买的服务器厂商找，将服务器IP填写到"主机"这一行

确认无误后点击连接；

2.登录

首次连接服务器需要登录连接

账号密码在你购买服务器时会在信息中出现,我这以腾讯云为例

知道用户名和密码后就可以通过XShell去填写并连接

密码

当连接成功后务必确认右上角的绿灯是否亮起

2.XFtp

Xftp 是由 NetSarang 公司开发的 Windows 平台 SFTP/FTP 文件传输客户端，支持安全、高效的远程文件管理和传输。

基本概述

Xftp 是一款运行于 Windows 系统的文件传输软件，支持 SFTP、FTP、FTPS、SCP 等多种协议，通过 SSH 加密通道保障数据传输安全。

核心功能

双窗格界面与可视化操作：左侧显示本地文件，右侧显示远程服务器文件，支持拖放操作和多标签会话管理。
文件传输与同步：支持上传、下载、服务器间直传、文件夹同步、断点续传及多线程加速。
文件管理：可查看文件内容、重命名、删除文件及修改权限，方便远程服务器管理。
身份验证与安全：支持主密码加密、SSH PKCS#11 协议及硬件令牌存储私钥，增强安全性。
高级功能：FXP 支持可缩短服务器间传输时间，支持传输队列管理、过滤规则、同步浏览和定时传输 NetSarang Computer。

与 Xshell 的配合

Xftp 可与同公司开发的 Xshell 终端模拟器联动，实现快速启动终端会话和文件管理的无缝结合，提高运维和开发效率。

第一步:新建会话连接

与远程服务器进行连接

第二步:输入信息连接

连接好后如图

左边为本机，右边为服务器上的文件

项目部署

项目上传到服务器有两种可选

一种是直接在XFtp中直接将项目文件夹拖拽进服务器中
一种是通过git+github/gitee，先将项目上传，然后在XShell中通过git clone将项目克隆进服务器中(推荐)

这里比较推荐第二种方式，它能更好的管理控制功能的增删，良好的管理版本体验，更新简单；

这里以第二种方式做演示

1.将项目上传到gitee中

(如果不熟悉git上传可以参考上篇文章)

首先确保你的前后端文件中都有dockerfile以及根目录中有docker-compose.yml这两个是构建项目的核心。

2.在XShell中先cd到项目目录中去在clone

如果想要在想把它放在自己命名的目录可以先

bash 复制代码

cd /home/ubuntu

然后通过mkdir"命名" 以进行目录的创建

创建完毕后记得cd进创建的目录然后进行克隆

3.编辑配置文件

进到项目并克隆后首先要做的就是先配置好配置文件

通过：

bash 复制代码

cp .env.example .env

含义是复制一份你项目中的变量文件，创建一份你自己的本地配置文件；

.env文件中存放的都是项目中的密钥密码等重要内容，他在git上传时默认忽略，所以需要cp一份

通过

bash 复制代码

nano .env

进入到env文件的编辑页面

审查本地项目中的.env文件将信息填写上去后按顺序：

Ctrl+O:保存
Enter:确认
Ctrl+X:退出

4.检查配置文件

构建镜像前需要检查一次配置，确认必要配置完成

bash 复制代码

docker compose --env-file .env config --quiet

这行命令的意思是：

让Docker Compose读取 .env、检查所有必填变量和docker-compose.yml语法，但不构建、不启动容器。

逐行拆解一下作用就是

docker compose:告诉系统我要管理这个项目里的容器，后面的所有参数都基于当前目录下的 docker-compose.yml（或 compose.yaml）文件执行。
--env-file .env: 告诉 Docker Compose："去当前目录下找一个叫 .env 的文本文件，把里面的键值对（比如 TAG=1.0）提前读进内存，用来填补 docker-compose.yml 里的空白（即 ${变量名}）。"
config：这不是启动容器的命令，而是 "预览/验证/编译" 命令,把 docker-compose.yml、--env-file 传入的变量、以及你服务器shell里的环境变量全部合并、替换占位符 ，然后在终端打印出最终完整的、可执行的 YAML 配置文件
--quiet(静默模式)：抑制（隐藏）所有非必要的警告信息。

没有任何输出且回到命令提示符：检查成功。

5.构建

当上述命令执行完且无误后就可以准备执行构建命令了

bash 复制代码

docker compose build --pull backend

docker compose ：调用编排工具，读取当前目录下的**docker-compose.yml**。
build : 执行构建操作。它会去查找**docker-compose.yml** 中**backend** 服务下定义的**build** 路径（比如 ./backend），找到该目录下的 Dockerfile，然后按照指令从头生成一个新的镜像文件。
--pull : 核心参数 。它在开始构建backend镜像之前，会强制去Docker Hub(或你配置的私有仓库)检查一次**Dockerfile** 中FROM xxx所依赖的基础镜像（例如 FROM openjdk:17 或 FROM python:3.11）是否有更新版本。

bash 复制代码

docker compose build --pull frontend

6.读取与启动

复制代码

docker compose up -d

读取当前目录下的**docker-compose.yml**配置。
创建并启动 所有定义的服务容器（如果容器已存在且镜像有变化，会自动重新创建）。
-d 表示后台运行，启动后终端立即返回，不阻塞。

改行命令执行以后

如果本地没有镜像，自动拉取。
如果有**build**配置，且代码有变动，会重新构建再启动。
已经运行的容器，若配置或镜像改变，会被删除并重建。

7.查看状态

可通过下述命令进行查看

复制代码

docker compose ps

会显示当前镜像的运行状态

这时就可以通过公网去访问我们的项目了；

如图

常见问题与排查

在部署过程中，可能会遇到一些典型错误。以下是几个常见问题及其解决方法：

1. 端口占用错误

问题现象： 执行 docker compose up -d 时提示端口已被占用，例如 Bind for 0.0.0.0:8080 failed: port is already allocated。

原因： 服务器上已有其他服务（如另一个 Docker 容器、Nginx、或你的上一个项目）占用了 docker-compose.yml 中配置的端口。

解决步骤：

查看占用端口的进程：
bash 复制代码
```
sudo lsof -i :8080
```
或
bash 复制代码
```
sudo netstat -tlnp | grep :8080
```
停止占用进程（谨慎操作）： 如果确认是其他不需要的容器，可以停止并移除：
bash 复制代码
```
docker stop <容器名或ID>
docker rm <容器名或ID>
```
修改项目端口： 如果端口冲突无法解决，可以修改项目的 docker-compose.yml 文件，将对外暴露的端口改为一个未被占用的端口（例如从 8080:80 改为 8081:80）。

2. 权限不足错误

问题现象： 执行 Docker 命令时提示 permission denied 或 Got permission denied while trying to connect to the Docker daemon socket。

原因： 当前用户不在 docker 用户组中，无法直接操作 Docker 守护进程。

解决步骤：

将当前用户加入 docker 组：
bash 复制代码
```
sudo usermod -aG docker $USER
```
生效组权限： 退出当前 SSH 会话并重新登录，或者执行：
bash 复制代码
```
newgrp docker
```
验证： 执行以下命令不再报错即表示成功：
bash 复制代码
```
docker ps
```

3. .env 环境变量未生效

**问题现象：**应用启动后，读取到的环境变量是空的或默认值，导致数据库连接失败等功能异常。

原因：

.env 文件未创建或路径不正确。
.env 文件中的变量名与 docker-compose.yml 中引用的名称不匹配。
使用了错误的命令，未指定 --env-file 参数。

解决步骤：

确认文件存在且路径正确： 确保在 docker-compose.yml 同级目录下存在 .env 文件。
bash 复制代码
```
ls -la .env
```
检查变量名： 核对 .env 文件中的变量名（如 DB_PASSWORD=123456）是否与 docker-compose.yml 中 ${DB_PASSWORD} 的引用完全一致（注意大小写）。
使用正确的启动命令： 确保构建和启动时指定了环境文件：
bash 复制代码
```
docker compose --env-file .env up -d --build
```
验证变量已加载： 可以先用检查命令预览：
bash 复制代码
```
docker compose --env-file .env config
```
查看输出中变量的值是否已被正确替换。

4. 镜像构建失败

问题现象： 执行 docker compose build 时失败，提示 ERROR: failed to solve、Dockerfile not found 或依赖下载超时等。

原因：

Dockerfile 路径错误或文件不存在。
Dockerfile 中的指令有语法错误。
网络问题导致基础镜像拉取失败。
构建上下文缺少必要的文件。

解决步骤：

检查 Dockerfile： 确认 Dockerfile 存在于 docker-compose.yml 中 build.context 指定的目录下，并且文件名拼写正确。
逐行检查 Dockerfile 语法： 特别是 FROM, RUN, COPY 等指令的格式和路径。
尝试单独构建： 进入服务对应的目录，尝试单独构建以获取更详细的错误信息：
bash 复制代码
```
cd backend
docker build -t test-image .
```
更换镜像源： 如果是国内服务器，可以尝试为 Docker Daemon 配置国内镜像加速器，或修改 Dockerfile 中的 FROM 镜像为国内可访问的地址。
清理缓存后重试： 有时缓存会导致问题，可以清理后重试：
bash 复制代码
```
docker system prune -a
docker compose build --no-cache
```

遇到其他问题，可以查看 Docker Compose 更详细的日志：docker compose logs <服务名>，或在社区、搜索引擎中根据具体错误信息寻找解决方案。

多文件部署

当前以及如上文所示，成功部署了一个项目，当我们想在这个服务器上部署多个项目，该如何部署呢？

1.更改暴露端口

首先可以复用已经连接好的XFtp以及XShell,因为用的是同一个服务器

其次，主要是关注于第二个项目对外暴露的接口的端口号，只需要改需要对外暴露的那个/那些服务。(前后端都在一个compose里)

如图所示

将第二个项目的暴露的端口更改，避免构建失败

2.上传并克隆

将整理好的项目进行git上传

bash 复制代码

mkdir ~/project    
cd ~/project
git clone https://gitee.com/xxx/an-cheng.git ancheng
cd ancheng

3.编辑配置文件

使用命令打开复制配置文件并打开

bash 复制代码

cp .env.production.example .env.production
nano .env.production

按照本地项目对配置文件进行相应的配置

配置编辑完成后，保存并退出："Ctrl+O" + "回车" + "Ctrl+X"

4.构建

执行构建语句

bash 复制代码

docker compose --env-file .env.production up -d --build

该命令会构建需要构建的镜像，然后直接启动全部服务

5.放行

当前部署启动好后，我们去访问服务器地址:端口号无法进行访问，那是因为服务器未放行，所以我们需要在服务器中放行该端口

以下以腾讯云为例演示

找到防火墙

添加规则

放行后大概30s左右即可访问

常见问题

1.构建时Xshell与服务器断连

先cd进目录

复制代码

cd ~/project/an-cheng

输入命令

复制代码

pgrep -af 'docker compose.*build'

如果有输出，例如：

某个PID docker compose --env-file .env.production build api migrate web

说明构建仍在继续。接着查看日志：

bash 复制代码

tail -n 30 -f deploy-build.log

不要重新执行**build**命令。

但是如果**pgrep**没有输出，说明构建已经结束。这时先检查最终结果，不要直接重新构建：

bash 复制代码

tail -n 100 deploy-build.log

判断失败还是成功再决定后续

2.服务器太小，构建稍大

这时候建议时修改配置文件，先保留必要的功能，确保能够上线以及主要功能可用

本地修改完配置文件后使用git上传至仓库

先用下述命令查看上次的构建是否还在运行

复制代码

pgrep -af 'docker compose.*build'

若上条命令显示类似12345 docker compose ... build ..

则说明上次的构建仍在继续，这是可用执行

bash 复制代码

kill 12345

(12345)是按照你实际的PID进行编辑的

然后回到目录

复制代码

cd ~/project/an-cheng

执行拉取更新

复制代码

git pull --ff-only

接着重新开始校验并构建

bash 复制代码

docker compose --env-file .env.production config -q
nohup docker compose --env-file .env.production build api migrate web > deploy-build.log 2>&1 &
tail -n 30 -f deploy-build.log

三条命令分别是

先校验配置，不构建、不启动。无输出表示通过。
后台构建镜像。因为你已经发生过 Xshell 断线，使用nohub能保证断线后构建继续。
查看第二条命令的实时构建日志。

构建完后按Ctrl+C退出日志查看

然后执行构建更新

bash 复制代码

docker compose --env-file .env.production up -d
docker compose --env-file .env.production ps

构建完成后就可以去http://公网IP:8088去查看

小结

折腾完这一整套，最大的感受就是：Docker真香，但坑也是真的多。

从最开始连服务器都连不明白，到现在能熟练地docker compose up -d，中间也就掉了几百根头发吧。2核2G 的服务器虽然穷酸了点，但只要把端口规划好、镜像别乱堆积，跑两个前后端分离的项目完全没问题。

几个血泪教训再强调一下：

.env文件一定要配好，别偷懒，不然随便点点就发现功能用不了；
内存不够就精简功能，别硬塞，构建到一半卡死真的很绝望；
用Git管理项目，比直接拖文件优雅一百倍，更新也方便。

如果你也打算把期末项目或者小作业部署上线，希望这篇笔记能让你少走点弯路。毕竟咱们大学生，时间可以浪费在打游戏上，但不能浪费在反复配环境上。