考试阅卷系统 - 华为云部署新手教程

📌 项目概览与部署方案

项目技术栈

层级	技术	端口
前端	React + TypeScript + Vite + Ant Design	5174（生产）
后端	Python FastAPI + SQLAlchemy + Uvicorn	8010
数据库	SQLite（文件型，无需单独部署）	-

部署架构

用户浏览器

→

ECS 云服务器

前端 :5174

→

后端 :8010

→

SQLite 文件

为什么选 ECS？

最简单：一台服务器搞定全部，适合新手
成本低：SQLite 不需要额外买数据库
灵活：后续可以随时升级配置

本教程选择 华为云弹性云服务器 ECS + Ubuntu 22.04 操作系统，这是最通用、文档最多的组合。

1 购买华为云 ECS 服务器

1.1 注册华为云账号

访问华为云官网，点击右上角「注册」，按照提示完成注册和实名认证。

1.2 购买 ECS

登录后，在顶部搜索框输入「弹性云服务器 ECS」，点击进入
点击「购买弹性云服务器」
按照以下配置选择：

配置项	推荐选择	说明
计费模式	按需计费 / 包年包月	新手先用按需计费试试，稳定后转包月更便宜
区域	选离你最近的（如：北京四、上海一）	影响访问速度
CPU 架构	x86 计算	兼容性最好
规格	通用计算型 \| s6.large.2（2核4G）	💡 最低 2核2G 也能跑，但推荐 2核4G 更流畅
镜像	公共镜像 → Ubuntu → Ubuntu 22.04 64bit	本教程基于此系统
系统盘	通用型 SSD，40GB	足够用了
带宽	按流量计费，5Mbit/s	小流量场景省钱

1.3 设置登录凭证

在「高级配置」中设置登录方式：

密码方式（推荐新手）：设置 root 用户密码，请牢记！
密钥对方式：更安全，但需要生成密钥对

请务必记住你的服务器 公网 IP 地址 和 root 密码，后面会反复用到。

确认配置无误后，点击「立即购买」→ 「去支付」，等待一两分钟服务器就创建好了。

2 配置安全组（开放端口）

华为云默认只开放了 22 端口（SSH 登录用），我们需要手动开放项目要用的端口。

2.1 进入安全组配置

在 ECS 控制台，找到你的服务器，点击服务器名称进入详情
找到「安全组」标签页
点击安全组名称（如 default）进入配置

2.2 添加入方向规则

点击「添加规则」，依次添加以下规则：

优先级	策略	协议端口	类型	源地址	说明
1	允许	TCP:22	IPv4	0.0.0.0/0	SSH 远程登录
1	允许	TCP:5174	IPv4	0.0.0.0/0	前端访问端口
1	允许	TCP:8010	IPv4	0.0.0.0/0	后端 API 端口
1	允许	TCP:80	IPv4	0.0.0.0/0	HTTP（后面绑域名用）
1	允许	TCP:443	IPv4	0.0.0.0/0	HTTPS（后面绑域名用）

源地址填 0.0.0.0/0 表示允许所有 IP 访问。如果只有你自己用，可以填你电脑的公网 IP，更安全。

3 远程登录服务器

Windows 用户：使用 PowerShell

按下 Win + X，选择「Windows PowerShell」或「终端」，输入：

ssh root@你的服务器公网IP
# 例如：ssh root@123.45.67.89
    

第一次连接会提示「是否继续连接」，输入 yes 回车，然后输入密码（密码不会显示，输完直接回车）。

Mac 用户：使用终端

打开「终端」App，同样输入：

ssh root@你的服务器公网IP

登录成功后，你会看到类似 root@ecs-xxx:~# 的提示符，说明已经进入服务器了！

也可以使用华为云控制台的「远程登录」功能（VNC），在 ECS 详情页点击「远程登录」按钮即可。

4 安装运行环境

登录服务器后，依次执行以下命令。每输完一行按回车执行，等待完成再继续。

4.1 更新系统包

apt update && apt upgrade -y

这一步可能需要几分钟，耐心等待。

4.2 安装 Python 3 和 pip

apt install -y python3 python3-venv python3-pip git

验证安装：

python3 --version
# 输出类似 Python 3.10.x 就对了
    

4.3 安装 Node.js

前端构建需要 Node.js，我们安装 LTS 版本：

# 下载 Node.js 安装脚本
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -

# 安装 Node.js
apt install -y nodejs

# 验证安装
node --version
npm --version
# 输出 v20.x.x 和 10.x.x 就对了
    

环境安装完成！现在有了 Python、Node.js 和 Git，可以部署项目了。

5 上传项目代码到服务器

有两种方式上传代码，选择你方便的一种：

方式一：Git 克隆（推荐，如果代码在 Git 仓库）

如果你的代码已经推送到 Gitee / GitHub / GitLab 等平台：

cd /opt
git clone 你的仓库地址 score-query
# 例如：git clone https://gitee.com/你的用户名/score-query.git

cd score-query
ls
# 应该能看到 backend、frontend、scripts 等目录
    

方式二：本地上传（适合代码在本地电脑）

Windows 用户：下载 WinSCP 或使用 PuTTY 的 pscp

Mac 用户：在本地终端执行：

scp -r /本地项目路径 root@你的服务器IP:/opt/score-query

如果你用的是 VS Code，可以安装「Remote - SSH」插件，直接在 VS Code 里编辑服务器上的文件，非常方便！

6 安装项目依赖

假设项目在 /opt/score-query 目录下：

6.1 安装后端 Python 依赖

cd /opt/score-query/backend

# 创建虚拟环境（推荐，隔离依赖）
python3 -m venv .venv

# 激活虚拟环境并安装依赖
source .venv/bin/activate
pip install -r requirements.txt

# 等待安装完成，验证一下
python -c "import fastapi; print('FastAPI 版本:', fastapi.__version__)"
    

6.2 安装前端 Node.js 依赖

cd /opt/score-query/frontend

# 安装依赖，可能需要几分钟
npm install

# 验证
npm run build
# 如果能成功构建出 dist 目录就说明没问题
    

如果 npm install 很慢，可以切换到国内镜像：
npm config set registry https://registry.npmmirror.com

7 初始化数据库与管理员

7.1 创建数据目录

cd /opt/score-query/backend
mkdir -p data uploads
    

7.2 初始化管理员账号

cd /opt/score-query/backend
source .venv/bin/activate
python scripts/seed_admin.py
    

默认账号：
管理员：admin / 密码：admin123
阅卷员：grader / 密码：grader123
上线后请务必修改默认密码！

8 启动服务并验证

8.1 使用项目自带脚本启动

项目已经提供了方便的启动脚本：

cd /opt/score-query

# 给脚本添加执行权限（首次需要）
chmod +x scripts/*.sh

# 启动全部服务（生产模式）
./scripts/start.sh
    

启动成功后，你会看到类似输出：

后端已启动 → http://127.0.0.1:8010
前端生产 → http://0.0.0.0:5174
    

8.2 验证服务是否正常

检查进程是否在运行：

./scripts/status.sh
# 或
ps aux | grep uvicorn
ps aux | grep vite
    

检查端口是否监听：

ss -tlnp | grep -E '5174|8010'

8.3 在浏览器访问

打开浏览器，访问：

http://你的服务器公网IP:5174

如果能看到登录页面，输入 admin / admin123 能成功登录，那么恭喜你，部署成功了！🎉

8.4 常用命令

命令	作用
./scripts/start.sh	启动全部服务（生产模式）
./scripts/stop.sh	停止全部服务
./scripts/restart.sh	重启全部服务
./scripts/status.sh	查看服务状态
./scripts/build-frontend.sh	重新构建前端

8.5 查看日志

# 后端日志
tail -f logs/backend.log

# 前端日志
tail -f logs/frontend.log
    

按 Ctrl + C 退出日志查看。

9 配置开机自启（强烈推荐）

前面的方式启动后，如果服务器重启，服务不会自动恢复。我们配置 systemd 服务来实现开机自启。

9.1 创建后端服务

cat > /etc/systemd/system/score-backend.service << 'EOF'
[Unit]
Description=Score Query Backend (FastAPI)
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/score-query/backend
ExecStart=/opt/score-query/backend/.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8010
Restart=always
RestartSec=5
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target
EOF
    

9.2 创建前端服务

cat > /etc/systemd/system/score-frontend.service << 'EOF'
[Unit]
Description=Score Query Frontend (Vite Preview)
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/score-query/frontend
ExecStart=/usr/bin/npm run preview
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
    

9.3 启用并启动服务

# 先停止之前的脚本启动的服务
cd /opt/score-query && ./scripts/stop.sh

# 重新加载 systemd 配置
systemctl daemon-reload

# 设置开机自启
systemctl enable score-backend score-frontend

# 启动服务
systemctl start score-backend score-frontend

# 查看状态
systemctl status score-backend
systemctl status score-frontend
    

看到 active (running) 就说明配置成功了！服务器重启后服务会自动启动。

9.4 systemd 常用命令

命令	作用
systemctl start 服务名	启动服务
systemctl stop 服务名	停止服务
systemctl restart 服务名	重启服务
systemctl status 服务名	查看服务状态
journalctl -u 服务名 -f	查看服务日志

10 绑定域名（可选进阶）

用 IP 访问不太方便，也不专业。我们可以绑定一个域名。

10.1 购买域名

在华为云「域名注册」服务购买一个域名，例如 yourdomain.com。

10.2 配置 DNS 解析

进入「云解析服务 DNS」
找到你的域名，点击「解析」
添加记录：

主机记录	类型	值
grader（或 www）	A	你的服务器公网IP

等待几分钟解析生效。

10.3 修改 CORS 配置

因为项目有 CORS 跨域限制，需要把你的域名加到允许列表中。创建环境变量配置：

cat > /opt/score-query/.env << 'EOF'
CORS_ORIGINS="http://grader.yourdomain.com,https://grader.yourdomain.com,http://localhost:5174"
JWT_SECRET="这里改成一个随机的长字符串，比如 mashuang123456!@#"
EOF
    

然后修改 systemd 服务加载这个环境变量：

sed -i '/ExecStart/i EnvironmentFile=/opt/score-query/.env' /etc/systemd/system/score-backend.service
systemctl daemon-reload
systemctl restart score-backend
    

10.4 修改前端 vite 配置中的 allowedHosts

编辑 /opt/score-query/frontend/vite.config.ts，把你的域名加到 allowedHosts 数组中，然后重新构建：

cd /opt/score-query/frontend
npm run build
systemctl restart score-frontend
    

10.5 配置 Nginx 反向代理（推荐）

用 Nginx 做反向代理，可以直接用 80 端口访问，不需要加端口号：

# 安装 Nginx
apt install -y nginx

# 创建配置文件
cat > /etc/nginx/sites-available/score-query << 'EOF'
server {
    listen 80;
    server_name grader.yourdomain.com;

    # 前端静态文件（也可以继续用 vite preview，这里演示直接由 Nginx 托管）
    location / {
        proxy_pass http://127.0.0.1:5174;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
EOF

# 启用站点
ln -s /etc/nginx/sites-available/score-query /etc/nginx/sites-enabled/
rm /etc/nginx/sites-enabled/default

# 测试配置
nginx -t

# 重载 Nginx
systemctl reload nginx
    

现在就可以用 http://grader.yourdomain.com 直接访问了！

如果需要 HTTPS，可以用 Let's Encrypt 免费证书，安装 certbot 后执行：
apt install -y certbot python3-certbot-nginx && certbot --nginx

❓ 常见问题 FAQ

Q1: 浏览器访问不了怎么办？

按以下顺序排查：

确认安全组是否开放了 5174 端口
确认服务是否在运行：systemctl status score-backend score-frontend
在服务器本地测试：curl http://127.0.0.1:5174，能返回 HTML 说明服务正常
如果本地通、外网不通，基本是安全组或防火墙的问题
检查系统防火墙：ufw status，如果开了就 ufw allow 5174

Q2: 前端页面打开了，但登录/接口报错？

大概率是后端没启动或跨域配置问题：

确认后端在运行：systemctl status score-backend
本地测试后端：curl http://127.0.0.1:8010/docs，能看到 Swagger 文档说明正常
如果是跨域错误（浏览器 F12 控制台有 CORS 字样），检查 CORS_ORIGINS 配置是否包含你的访问地址

Q3: SQLite 数据库文件在哪？怎么备份？

数据库文件在 /opt/score-query/backend/data/app.db，直接复制这个文件就是备份。建议定期备份：

cp /opt/score-query/backend/data/app.db /opt/score-query/backend/data/app.db.bak.$(date +%Y%m%d)

Q4: 修改了代码怎么更新？

分两种情况：

改了前端代码：重新构建 → 重启前端
cd /opt/score-query/frontend && npm run build && systemctl restart score-frontend
改了后端代码：直接重启后端
systemctl restart score-backend

Q5: 服务器太卡了怎么办？

可以在华为云控制台「变更规格」升级配置。也可以优化：

用 Nginx 直接托管前端静态文件，关掉 vite preview（节省内存）
开启 gzip 压缩
如果数据量大，可以考虑把 SQLite 换成 MySQL

Q6: 忘记管理员密码怎么办？

重新运行 seed_admin.py 脚本会重置默认账号密码：

cd /opt/score-query/backend
source .venv/bin/activate
python scripts/seed_admin.py
        

Q7: 用脚本启动还是 systemd 启动？

推荐用 systemd，因为：

开机自动启动，服务器重启不怕
进程崩溃自动重启
统一的日志管理（journalctl）
更专业、更稳定

脚本方式适合临时调试使用。

🚀 考试阅卷系统 - 华为云部署新手教程

📑 目录

📌 项目概览与部署方案

项目技术栈

部署架构

为什么选 ECS？

1 购买华为云 ECS 服务器

1.1 注册华为云账号

1.2 购买 ECS

1.3 设置登录凭证

2 配置安全组（开放端口）

2.1 进入安全组配置

2.2 添加入方向规则

3 远程登录服务器

Windows 用户：使用 PowerShell

Mac 用户：使用终端

4 安装运行环境

4.1 更新系统包

4.2 安装 Python 3 和 pip

4.3 安装 Node.js

5 上传项目代码到服务器

方式一：Git 克隆（推荐，如果代码在 Git 仓库）

方式二：本地上传（适合代码在本地电脑）

6 安装项目依赖

6.1 安装后端 Python 依赖

6.2 安装前端 Node.js 依赖

7 初始化数据库与管理员

7.1 创建数据目录

7.2 初始化管理员账号

8 启动服务并验证

8.1 使用项目自带脚本启动

8.2 验证服务是否正常

8.3 在浏览器访问

8.4 常用命令

8.5 查看日志

9 配置开机自启（强烈推荐）

9.1 创建后端服务

9.2 创建前端服务

9.3 启用并启动服务

9.4 systemd 常用命令

10 绑定域名（可选进阶）

10.1 购买域名

10.2 配置 DNS 解析

10.3 修改 CORS 配置

10.4 修改前端 vite 配置中的 allowedHosts

10.5 配置 Nginx 反向代理（推荐）

❓ 常见问题 FAQ