fragmemo/docs/部署指南.md

fragmemo 部署指南

部署到华为云服务器（宝塔面板 + Ubuntu 22.04）

---

一、前置信息

项目	值
服务器 IP	113.44.249.175
操作系统	Ubuntu 22.04
宝塔面板	https://113.44.249.175:2026/527378
MySQL	已安装（宝塔管理）
Nginx	已安装（宝塔管理）
Gitea	http://113.44.249.175:4000
项目目录	/www/wwwroot/memo_server/（后端）
前端目录	/www/wwwroot/memo.fragford.cn/（前端静态文件）
对外端口	82（与 echo.fragford.cn 共用）
访问方式	http://113.44.249.175:82
备案通过后	https://memo.fragford.cn

---

二、服务器操作步骤

2.1 创建 MySQL 数据库（可选，目前使用 SQLite）

打开宝塔面板 → 数据库 → 添加数据库：

项目	值
数据库名	fragmemo
用户名	fragmemo
密码	自己设一个（记住它后面要用）
访问权限	127.0.0.1（本地，不要对外开放）

创建后修改 /www/wwwroot/memo_server/.env 中的 DATABASE_URL：

DATABASE_URL=mysql+asyncmy://fragmemo:密码@127.0.0.1:3306/fragmemo

然后重启后端：systemctl restart memo-server

2.2 部署前端

本地 Mac 上，一键构建并同步到服务器：

cd /Users/a58/Documents/fragfordspace/fragmemo/memo.fragford.cn
npm run deploy

2.3 部署后端

本地 Mac 上，一键同步并重启：

cd /Users/a58/Documents/fragfordspace/fragmemo/memo_server
bash deploy.sh

或者手动操作：

# SSH 到服务器
ssh root@113.44.249.175

# 拉取最新代码
cd /www/wwwroot/memo_server
git pull

# 激活虚拟环境 & 安装依赖
source venv/bin/activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 重启
systemctl restart memo-server

2.4 查看日志

journalctl -u memo-server -f

2.5 验证部署

浏览器访问 http://113.44.249.175:82，你应该能看到 fragmemo 首页。

验证 API 是否正常：

curl http://113.44.249.175:82/api/v1/auth/health

---

三、本地开发日常流程

以后你改了代码，部署流程就是：

# 前端部署（一键）
cd /Users/a58/Documents/fragfordspace/fragmemo/memo.fragford.cn
bash deploy.sh

# 后端部署（一键）
cd /Users/a58/Documents/fragfordspace/fragmemo/memo_server
bash deploy.sh

两个脚本都是独立的 shell 脚本（不是 npm script），都有：

• ✅ 分支检查（只能在 main 部署）
• ✅ 工作区干净检查
• ✅ 版本信息展示（提交哈希、作者、时间）
• ✅ 构建/同步过程
• ✅ 服务器端发布日志记录（DEPLOY_LOG.md）
• ✅ 部署结果汇总

---

四、ICP 备案通过后（HTTPS + 域名）

备案通过后，把 Nginx 配置改为：

server {
    listen 443 ssl;
    server_name memo.fragford.cn;

    ssl_certificate /www/server/panel/vhost/cert/memo.fragford.cn/fullchain.pem;
    ssl_certificate_key /www/server/panel/vhost/cert/memo.fragford.cn/privkey.pem;

    root /www/wwwroot/memo.fragford.cn;
    index 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 / {
        try_files $uri $uri/ /index.html;
    }
}

server {
    listen 80;
    server_name memo.fragford.cn;
    return 301 https://$host$request_uri;
}

在宝塔面板可以直接申请 Let's Encrypt 免费 SSL 证书。

---

五、常见问题

Q：端口 8000 被占用了？

在宝塔 Python 项目管理器里改监听端口，或先 pkill -f uvicorn 杀掉旧进程。

Q：前端页面空白、接口报错？

检查 Nginx 配置里 /api/ 的 proxy_pass 是否正确指向了后端的地址和端口。

Q：数据库连不上？

确认 .env 里的 DATABASE_URL 中的密码、用户名、数据库名都正确。可以先在服务器上用命令行测试：

mysql -u fragmemo -p -h 127.0.0.1

Q：后端启动了但访问 502？

检查后端是否真的在运行：curl http://127.0.0.1:8000/health。如果没运行，去宝塔 Python 项目管理器启动它。

Q：部署后端时 pip install 很慢？

可以临时换国内镜像：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple