🍉 菜瓜记账 & MyBill
Docker 多项目部署文档

一、整体架构

4 个 Docker 容器在同一台服务器运行，通过 shared_net 网络互通。Nginx 统一入口，按 URL 路径分发到各后端。

架构图

  ┌─ 用户 ──────────────────────────────────┐
  │  https://cmetamind.cn/xxx                │
  └─────────────────┬───────────────────────-┘
                    ▼
  ┌──────────────────────────────────────────┐
  │     Nginx listen 443 SSL                 │
  │     HTTP 80 → 301 HTTPS                 │
  └────┬──────────┬───────────┬─────────────-┘
       │          │           │
       ▼          ▼           ▼
   ┌──────┐  ┌────────┐  ┌──────────┐
   │  /   │  │ /mb/   │  │ /mb-api  │→ FastAPI
   │文档  │  │前端     │  │ /bill-api│→ MyBill
   └──────┘  └────────┘  └────┬─────┘
                               │
                               ▼
                        ┌──────────────┐
                        │  MySQL 8.0   │
                        │ melon_ledger │
                        │ bill         │
                        └──────────────┘

访问路径

二、目录结构

根目录 /home/deploy/docker-new/

├── infrastructure/        ← 基础设施
│   ├── docker-compose.yml ← 编排文件
│   ├── .env              ← MySQL 密码
│   ├── mysql/
│   │   ├── conf/my.cnf
│   │   └── init/
│   │       ├── 01-melon-ledger.sql  ← 建库+用户
│   │       └── 02-mybill.sql
│   ├── nginx/
│   │   ├── nginx.conf
│   │   └── conf.d/
│   │       └── melon-ledger.conf ← 全部路由
│   └── ssl/
│       ├── fullchain.pem   ← SSL 证书
│       └── privkey.pem     ← SSL 私钥
├── melon-ledger/          ← 菜瓜记账
│   ├── backend/
│   │   ├── Dockerfile
│   │   ├── requirements.txt
│   │   ├── .env
│   │   ├── main.py
│   │   ├── app/           ← 业务代码
│   │   └── migrations/    ← Alembic 迁移
│   └── frontend/dist/     ← 构建产物
├── mybill/                ← MyBill
│   ├── Dockerfile
│   ├── index.js
│   ├── bill.js
│   └── package.json
├── static/                ← 根路径静态文件
│   └── index.html         ← 本文件
└── scripts/               ← 备份

三、环境配置

文件列表及关键配置（密码用占位符替代）：

infrastructure/.env

MYSQL_ROOT_PASSWORD=<MYSQL_ROOT_PASSWORD>

melon-ledger/backend/.env

MYSQL_ROOT_PASSWORD=<MYSQL_ROOT_PASSWORD>
MYSQL_USER=melon
MYSQL_PASSWORD=<MELON_DB_PASSWORD>
MYSQL_DATABASE=melon_ledger
JWT_SECRET_KEY=<JWT_SECRET_KEY>
# Redis 未部署，自动降级
# Neo4j 未部署，自动跳过
DEEPSEEK_API_KEY=<DEEPSEEK_API_KEY>
DEEPSEEK_MODEL=deepseek-chat

mybill/.env

MYBILL_DB_PASSWORD=<MYBILL_DB_PASSWORD>

建表说明

MySQL init SQL 只建库和用户，不建表：

• melon_ledger：首次运行 docker exec ml_backend alembic upgrade head
• bill：从 melon_ledger 导出建表语句执行（4 张表：user_info, bill_info, income_expenditure_type, balance）

四、Nginx 路由说明

单配置文件 infrastructure/nginx/conf.d/melon-ledger.conf

关键配置片段

# melon-ledger API （路由前缀 /api/xxx）
location /mb-api/ {
    rewrite ^/mb-api(/.*)$ $1 break;
    proxy_pass http://ml_backend;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

# mybill API （路由 /users, /types 等）
location /bill-api/ {
    set $mybill_upstream "http://ml_mybill:3000";
    rewrite ^/bill-api(/.*)$ $1 break;
    proxy_pass $mybill_upstream;
}

SSL 证书

当前覆盖 cmetamind.cn 和 www.cmetamind.cn。如需添加 bill.cmetamind.cn，替换 ssl/fullchain.pem 和 ssl/privkey.pem 后重启 nginx。

五、日常运维操作

以下命令在 ~/docker-new/infrastructure/ 下执行。

# 查看所有容器
docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# 查看日志
docker logs -f ml_backend   # 实时日志
docker logs -f ml_mybill    # mybill 日志
docker logs --tail 50 ml_backend  # 最近 50 行

# 重启
docker compose restart nginx
docker compose restart ml_backend

# 重新构建+启动（代码更新后）
docker compose up -d --build ml_backend

# 热重载 Nginx（不中断连接）
docker exec infra_nginx nginx -t     # 语法检查
docker exec infra_nginx nginx -s reload

# 数据库
docker exec infra_mysql mysql -uroot -p melon_ledger -e "SHOW TABLES;"
docker exec ml_backend alembic upgrade head  # 迁移

# 前端更新（本地构建后上传 scp，无需重启 nginx）
scp -r dist/* user@server:/home/deploy/docker-new/melon-ledger/frontend/dist/

六、添加新项目到 Docker

1. 写 Dockerfile — 项目根目录创建，参考 mybill/Dockerfile
2. 加 docker-compose — 在 infrastructure/docker-compose.yml 添加 service 配置，加上 networks: - shared_net
3. 加 Nginx 路由 — 在 melon-ledger.conf 的 server block 添加新的 location /xxx/
4. 启动 — docker compose up -d --build 服务名 + docker compose restart nginx

七、踩坑记录 🐛

八、常用命令速查表