从 localhost 到公网:一次项目部署记录
在此之前,「部署」对我而言只是两个抽象的字。
代码在本地跑通,浏览器打开 localhost:5173,一切正常。这种感觉很容易让人误以为事情已经完成了——直到你把这条地址发给别人,对方回一句「打不开」。
本地和公网之间隔着的不是一条命令,而是一整套你得亲手搭起来的东西:一台机器、一个能对外开门的端口、一个装着数据的库、一个常驻的进程、一个把请求分发给正确位置的入口,以及一层和代码毫无关系、但决定你能不能上线的行政手续。
那天我从买下服务器到公网可访问,用了大约四小时。中间没有一次是「按教程走完就好了」——每一步都有一两个需要你自己判断的岔口。
这篇文章是把那四小时重新走一遍。不是操作手册(手册会过期),而是把每个选择背后的理由和踩下去才知道的坑留下来。
先说清楚
文中出现的 IP、域名、库名、账号、路径全部为示例值,不指向任何真实在运行的服务器。技术方案是通用的,细节请按自己的环境替换。
先看清:一台服务器上到底跑着什么
买机器之前,我做的第一件事不是打开购买页,而是在纸上画了一张图——请求从浏览器出发,一路走到数据库,中间要经过哪些关卡。
这张图画不出来,后面每一步都会变成盲目照抄。画出来了,你就知道每个配置项在解决哪个位置的问题。
图 1 一次页面请求的完整链路。所有的配置错误,最终都能落回到这张图的某个箭头上。
看着这张图,很多事情忽然就通了:
- 为什么数据库绝对不能对公网开放——它只应该被左侧的 8080 访问,和浏览器没有任何直接关系;
- 为什么前端刷新页面会 404——因为前端路由的地址在磁盘上根本不存在文件;
- 为什么改完前端只要覆盖文件,而改完后端必须重启——nginx 每次请求都去磁盘读,Java 程序把代码装在内存里。
部署的大部分痛苦,不是命令记不住,而是不知道自己正在改这张图上的哪一根线。
买机器:藏在默认值里的两个坑
配置清单本身没什么可说的,入门款足够跑一个教学规模的项目。真正值得记下来的是购买页上两个会悄无声息毁掉你下午的默认值。
| 配置项 | 选择 | 背后的理由 |
|---|---|---|
| 付费模式 | 包年包月 | 长期用单价最低;按量适合短期试验 |
| 规格 | 2 核 2G | 能跑起来,但内存是全程最紧的资源 |
| 镜像 | Ubuntu 22.04 | 省内存,且绝大多数部署资料都以它为前提 |
| 系统盘 | ESSD 40 GiB | 最低档够用;静态资源和附件不该堆在系统盘 |
| 带宽 | 按流量 · 峰值 100 Mbps | 流量小的时候按量计费远便宜于固定带宽 |
坑 01
✕镜像差点选了 Windows Server
购买页的默认镜像被切到了 Windows Server,而且是连图形界面都没有的 Server Core 版本。2G 内存上,光系统本身就能吃掉一半,剩下的留给数据库和 JVM,基本等于宣布失败。
改回 Linux。顺手记住:2G 内存不是「小一点的服务器」,而是「每一百兆都要算账的服务器」。
坑 02
✕按流量计费,但峰值带宽是 0
这是最阴的一个。选了「按使用流量」,页面上带宽峰值默认 0,于是机器买回来了、系统装好了、SSH 也能连——但公网完全不通。你会以为是安全组、是防火墙、是 nginx,排查一圈才发现网卡压根没被分配出口带宽。
按流量计费也必须设一个峰值(比如 100 Mbps)。峰值只限速,不额外收费;设成 0 才是真的不通。
安全组:白名单思维,而不是黑名单
安全组的规则很容易被误解成「禁止什么」。实际上它是反过来的:没被放行的,一律进不来。默认全关,你只需要开口。
| 端口 | 用途 | 是否对公网开放 |
|---|---|---|
22 | SSH 登录 | 是(最好限制为自己的固定 IP) |
80 / 443 | 网站唯一入口 | 是 |
面板端口 | 服务器管理面板 | 是(强烈建议改端口 + 加安全入口) |
8080 | 后端应用 | 否——只经 nginx 内部转发 |
3306 | MySQL | 否——永远不要 |
6379 | Redis | 否——永远不要 |
一个判断原则
对外只留 80/443 一个入口。后端端口和数据库端口即使在服务器内部,也应该只监听 127.0.0.1,而不是 0.0.0.0。安全组是外面的锁,监听地址是里面的锁——两把锁都要有。
安家:先给 2G 内存留一条退路
连上服务器之后,第一件事不是装软件,而是加 swap。
理由很朴素:这台机器要同时装下面板、MySQL、Nginx 和 JVM。任何一次内存峰值——比如 MySQL 启动时申请缓冲池、或者 Maven 在服务器上跑一次构建——都可能触发 OOM Killer,把某个进程直接杀掉。而它杀谁是不可预测的,表现就是「服务莫名其妙停了」。
swap
fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
# 写进 fstab,重启后自动挂载
echo '/swapfile none swap sw 0 0' >> /etc/fstab
# 优先用物理内存,实在不够才动用 swap
echo 'vm.swappiness=10' >> /etc/sysctl.conf
sysctl -p
free -h # 看到 Swap: 2.0Gi 才算成了
swappiness=10 这一行值得单独说一句。swap 不是用来提升性能的,它是安全气囊——平时不该弹出来。默认值 60 意味着系统会相当积极地往磁盘上换页,在 2G 机器上反而拖慢一切。
软件栈:版本选择里有判断
| 软件 | 关键判断 |
|---|---|
| MySQL 8.0 | 小内存机器必须选极速安装。编译安装需要 3G 以上内存,2G 机器会在中途失败,而且失败得很沉默 |
| Nginx | 版本号第二位是偶数的是稳定版,奇数是开发版。选稳定分支 |
| JDK | 版本必须和 pom.xml 里写死的 java.version 对齐。差一个版本就编译不过 |
经验
面板装完会输出面板地址、随机端口、安全入口路径和初始账号密码。这几行信息只显示一次,截屏存下来。忘了也别慌,服务器上执行 bt default 可以重新打印。
搬家:数据库与「最小权限」的直觉
数据从本地搬到服务器,技术上只有两步:导出、导入。但这里有个细节,几乎所有人第一次做都会遇到。
导出
local · mysqldump
mysqldump -u root -p \
--default-character-set=utf8mb4 \
--databases --result-file=D:/dump.sql app_db
--default-character-set=utf8mb4 不能省。中文乱码的根源往往不在数据库,而在这条导出命令没带字符集。
导入,以及一个必须验证的习惯
面板里上传 SQL 文件、点「导入」、弹出「导入成功」——然后就以为成了。这是最容易翻车的地方:某些面板的导入功能依赖 phpMyAdmin,没装就没真正执行,提示却照常给。
server · verify
# 不要相信提示,相信这张表
mysql -u app_user -p app_db -e "SHOW TABLES;"
看到表全部列出来,这一步才算完成。「操作提示成功」和「事实成立」是两件事——这个习惯后面还会救你很多次。
为什么不用 root
本地开发习惯用 root,因为方便。但服务器上的 root 密码通常是面板随机生成的,你根本不知道,也不该去改它。更重要的是,应用本来就不需要 root 的权限。
| 能力 | root | 应用专用账号 |
|---|---|---|
| 对业务库增删改查 | 可以 | 可以 |
| 访问其他库 | 可以 | 不行 |
| 建库、建用户、改密码 | 可以 | 不行 |
建账号时那一条 GRANT,实际上设了两层笼子:只能碰这一个库,只能从本机连接。就算密码哪天泄露了,攻击者连不上来;就算真被进来了,损失被锁死在一个库里。
权限设计的目的不是「方便的时候够用」,而是「出事的时候损失可控」。
后端:一个 jar 的生死
后端部署的本质非常简单:把打包好的 jar 传上去,用一个常驻进程跑起来。麻烦全在「常驻」和「配置」这两个词上。
打包时第一个坑:JAVA_HOME 和 PATH 不是一回事
命令行执行 java -version,显示 21。执行 Maven 打包,报 release version 21 not supported。
原因是两个环境变量指向了不同的 JDK:PATH 决定你敲 java 时用哪个,JAVA_HOME 决定 Maven 去哪个目录找 JDK。它们可以不一致,于是就有了「命令行显示 21,构建却认为你在用 11」的迷惑现场。
powershell · build
# 临时覆盖,只在当前会话生效,不影响系统配置
$env:JAVA_HOME = 'C:\path\to\jdk-21'
mvn clean package -DskipTests
启动:常驻进程怎么写才不出事
server · start
cd /www/wwwroot/app-api
nohup java -jar app.jar \
--spring.datasource.username=app_user \
> app.log 2>&1 &
这行命令有三部分,每一部分都在解决一个具体问题:
nohup ... &——后台常驻。不加的话,终端一关,进程跟着死;--spring.datasource.username——覆盖 jar 内部配置。本地的 yml 写的是 root,服务器上必须换。这个参数漏了,表现是启动正常但一访问数据库就报错;> app.log 2>&1——标准输出和错误都写进日志文件。没有这半句,出错时你什么都看不到。
最容易忽略的一件事
服务器重启后,jar 不会自动启动。别等到某天发现网站打不开,才想起这件事。要么写 systemd 单元,要么准备一个管理脚本。
把启停固化成一个脚本
手敲命令的问题是:你会记错参数、会漏掉环境变量、会在凌晨两点手抖。一个几十行的 app.sh 就能解决:
app.sh · 用法
./app.sh start | stop | restart | status | log
脚本里做三件事:source 一个环境变量文件、用 stop 时等进程真正退出再 start(否则端口还占着,新进程起不来)、把所有输出追加进同一个日志。
环境变量:密钥不该进代码库
项目里凡是读写对象存储、发短信、调第三方 API 的地方,都需要密钥。本地开发时这些通常配在系统环境变量里,于是本地一切正常,一上服务器就 500——因为服务器上没有这些变量。
oss-env.sh · chmod 600
# 单独一个文件,权限 600,只有 root 可读
export OSS_ACCESS_KEY_ID="***"
export OSS_ACCESS_KEY_SECRET="***"
启动脚本里 source 它。以后加任何变量都往这里加,然后 restart。密钥永远不进 Git,也不出现在启动命令的进程列表里——后者是个真实问题,ps aux 能看见任何写在命令行参数里的密码。
前端:nginx 两行配置决定了整个架构
前端是构建产物:一个 index.html 加一个 assets/ 目录,压缩混淆过,改不了也不需要改。建站、上传、解压,然后写配置。
nginx 配置里真正重要的只有两段,它们各自解决一个只有上线后才会暴露的问题。
nginx.conf · server 块
# 1. 单页应用刷新不 404
location / {
try_files $uri $uri/ /index.html;
}
# 2. /api 开头的请求转给本机后端
location ^~ /api/ {
rewrite ^/api/(.*)$ /$1 break;
proxy_pass http://127.0.0.1:8080;
}
为什么第一段必须写
单页应用的路由是浏览器端的。用户访问 /student,这个地址在服务器磁盘上并不存在任何文件——它只是前端路由表里的一个键。
直接刷新时,浏览器向服务器要 /student,服务器找不到,返回 404。而站内跳转是 JS 改的地址,不经过服务器,所以不会出错。这就是「本地好好的,一刷新就 404」的全部原因。
try_files $uri $uri/ /index.html 的意思是:先找这个文件,再找这个目录,都没有就把 index.html 交出去,让前端路由自己处理。
为什么第二段要用 ^~
/api/ 前缀的请求要转给后端,而且转发前得把 /api 去掉——后端的接口路径里没有这个前缀。rewrite ... break 做这件事,proxy_pass 指向本机 8080。
^~ 的作用是:一旦匹配上这个前缀,就不再尝试后面的正则 location。避免被其他规则抢走,是个省心的写法。
为什么这样是对的
前端和后端同源了——浏览器只跟 80 端口说话,不再有跨域问题,cookie 也自然。相比给后端单独开一个端口再配 CORS,这是更干净的做法。
前端更新和后端更新的本质差异
这个差异值得单独记住,因为它解释了两种完全不同的操作流程:
- 前端:nginx 每次请求都现场从磁盘读文件。所以覆盖文件即刻生效,不用重启任何服务。浏览器有缓存,必要时 Ctrl+F5。
- 后端:Java 程序把代码装进内存运行。换文件没用,必须重启进程。
顺带一个细节:构建产物带 hash 文件名,新版本意味着新文件名,旧文件不会自动消失。所以覆盖前先清空旧目录,否则磁盘会慢慢堆满历史版本。
域名与备案:一段和代码无关的现实
技术部分到这里就结束了。但如果服务器在国内,还有一道门槛和代码毫无关系。
域名后缀的价格陷阱
第一次买域名,很容易被「首年 1 元」吸引。这里有个结构性的商业逻辑:便宜的是首年价,商家赚的是续费价。像打印机便宜卖、墨盒贵。
| 后缀 | 首年(促销) | 续费 | 说明 |
|---|---|---|---|
| .cn | 约 30 元 | 约 39 元 | 价格稳定透明,长期持有最划算 |
| .com | 约 78 元 | 约 85 元 | 最通用,短词基本被抢光 |
| .xyz | 1 元起 | 约 75 元 | 新后缀里认知度较高 |
| .icu 等 | 1 元起 | 约 75 元+ | 缩写联想不佳,不建议做正式站 |
按三年算,1 元首年的后缀反而比 .cn 贵。这是个简单的算术,但促销页从不帮你算。
ICP 备案:三个主体绑在一起
国内服务器上用域名走 80/443 必须备案,否则会被拦截。它的本质是登记一件事:谁(主体)+ 哪个网站(域名)+ 挂在哪台服务器(接入商),三者绑定,备案号发给域名。
| 阶段 | 大致耗时 |
|---|---|
| 提交材料(主体、网站信息、人脸核验) | 当天 |
| 接入商初审 | 1~2 天,注意接核实电话 |
| 工信部短信核验 | 收到后 24 小时内必须完成 |
| 管局审核 | 1~2 周 |
填表经验(都是被退回换来的)
① 网站名称不能含「空间、资讯、网络、工作室、科技、博客、论坛、在线、社区、平台、中心」这类词——它们暗示了某种需要前置审批的业务形态。用朴素的名字,比如「某某的学习笔记」。
② 网站内容类别选「博客 / 个人空间」或「其他」,别选新闻、出版、教育、医疗——那些需要额外资质。
③ 备注不能空,通常要求 20 字以上,写清楚网站用途。
备案的一些结构性认识
- 备案以域名为单位,以服务器为依托,以你为归属;
- 子域名不需要单独备案。主域名备案后,
blog.example.com、api.example.com全部自动覆盖; - 所以合理玩法是:一个主域名当容器,各项目走子域名,一次备案长期使用;
- 换服务器但同接入商,基本不影响;换接入商要做「接入备案」;买新域名要做「新增网站备案」(主体信息可复用,很快)。
另外,ICP 通过后还有公安备案,通常在网站开通后 30 日内完成。这一步反而简单,大部分信息可以从备案系统同步过去。
七个坑,一张清单
把上面散落各处的坑收拢在一处,当作以后的自检表。
01
镜像默认是 Windows
2G 内存跑 Windows Server 是灾难。 选 Linux,Ubuntu 22.04 最省心。
02
按流量计费,峰值带宽为 0
机器能连上但公网不通,排查半天以为是安全组。 设一个峰值,比如 100 Mbps。峰值只限速不收费。
03
数据库「导入成功」但里面是空的
面板的导入依赖 phpMyAdmin,没装就不会真正执行,提示却照给。 命令行 SHOW TABLES 验证,看到表才算数。
04
Maven 打包报 release version 21 not supported
java -version 显示 21,但 JAVA_HOME 指向 11。 构建前临时设 JAVA_HOME,或在 IDE 内构建(用 IDE 自己的 JDK 配置)。
05
启动成功,但一访问数据库就报错
jar 内配置写的是 root,服务器上是专用账号。 启动参数覆盖 datasource,并把它固化进脚本,避免下次漏掉。
06
文件上传接口报 500
SDK 从环境变量读密钥,本地有、服务器没有。 密钥写进独立的 env 文件(权限 600),启动脚本 source 它。
07
备案被退回
网站名称含禁用词,备注留空。 换朴素名称,备注写满用途说明。
七个坑里,只有两个是「技术」问题,其余都是默认值、提示语、环境差异造成的。这大概是部署最让人沮丧也最让人清醒的地方。
三个「原来如此」
技术细节会忘,但这三个理解留下来之后,再看任何部署文档都不容易迷路。
端口是门牌号,安全组是门禁
IP 是楼地址,端口是门牌号。一台机器上跑着多个服务,各占一个门牌。而地址里不写端口时,浏览器默认走 80——这就是为什么线上访问不用写 :80,而本地用了 90 端口就必须显式写出来。
安全组则是这栋楼的门禁名单。它不关心你是谁,只关心你敲的是不是被允许的门。
文件服务器 vs 内存中的程序
nginx 是文件服务器,每个请求都去磁盘读;Java 程序把代码加载进内存运行。这个差异决定了一切更新流程:覆盖即生效还是必须重启。
理解了这个,你就不会再问「为什么改个前端还要重启后端」。
「提示成功」不等于「事实成立」
这可能是那天最重要的收获。面板说导入成功、命令行说部署完成、服务说启动正常——这些都只是某个程序在某个时刻给出的结论。真正的事实需要用另一种方式验证:查表、看端口、发一个请求。
部署教会我的不是某个命令,而是一种习惯:每个「成功」都要有一个独立的证据。
fin
尾声
四小时结束时,我在浏览器里输入那个 IP,页面出来了。
说实话,那一瞬间的成就感并不来自「网站能访问了」——而是来自一件更小的事:这台机器上的每一个部件,我知道它在哪、为什么在那、坏了会怎样。
在此之前,localhost 是一个温柔的幻觉。它让所有东西看起来都能用,因为所有东西都在同一个房间里,没有网络、没有权限、没有别人的浏览器。部署就是把这个幻觉拆掉,把每个环节暴露在真实的条件下:带宽会限速、内存会用完、进程会死、提示会撒谎。
所以我现在觉得,部署不该被当成最后一步的杂活。它是一次对系统的压力测试,只不过测的不是性能,是你对自己写的东西到底理解多少。
那天晚上我把整个过程记了下来。写的时候才发现,真正花掉时间的不是任何一条命令,而是那些需要停下来想一想「这里为什么是这样」的时刻。
如果你也正要搬第一次家,希望这篇能帮你少停在几个路口。
文中所有 IP、域名、账号、路径均为示例,不对应任何实际在运行的服务器。
写于 某个周末的深夜
技术栈 Spring Boot 3 · MySQL 8 · Nginx · Ubuntu 22.04
用时 约四小时,其中两小时在排查