init fragmemo (memo SPA + go backend)

docs/部署指南.md

@@ -0,0 +1,178 @@
+# 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 上，一键构建并同步到服务器：
+```bash
+cd /Users/a58/Documents/fragfordspace/fragmemo/memo.fragford.cn
+npm run deploy
+```
+
+### 2.3 部署后端
+
+本地 Mac 上，一键同步并重启：
+```bash
+cd /Users/a58/Documents/fragfordspace/fragmemo/memo_server
+bash deploy.sh
+```
+
+或者手动操作：
+```bash
+# 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 查看日志
+```bash
+journalctl -u memo-server -f
+```
+
+### 2.5 验证部署
+
+浏览器访问 `http://113.44.249.175:82`，你应该能看到 fragmemo 首页。
+
+验证 API 是否正常：
+
+```bash
+curl http://113.44.249.175:82/api/v1/auth/health
+```
+
+---
+
+## 三、本地开发日常流程
+
+以后你改了代码，部署流程就是：
+
+```bash
+# 前端部署（一键）
+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 配置改为：
+
+```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 中的密码、用户名、数据库名都正确。可以先在服务器上用命令行测试：
+```bash
+mysql -u fragmemo -p -h 127.0.0.1
+```
+
+### Q：后端启动了但访问 502？
+检查后端是否真的在运行：`curl http://127.0.0.1:8000/health`。如果没运行，去宝塔 Python 项目管理器启动它。
+
+### Q：部署后端时 pip install 很慢？
+可以临时换国内镜像：
+```bash
+pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
+```