gin
6.1 KiB
CollabLedger
CollabLedger 是一个前后端分离的协作账本/后台管理项目。后端使用 Hono，前端包含 Web 管理端和 Taro 多端应用，根目录 Docker Compose 用于启动 MySQL 和 Redis。
项目架构
原仓库地址
当前项目是在以下开源项目基础上改造：
- 后端原仓库：https://github.com/valarchie/collab_ledger-Back-End
- Web 前端原仓库：https://github.com/valarchie/collab_ledger-front-end-pure
- Web UI 上游项目：https://github.com/pure-admin/vue-pure-admin
目录结构
CollabLedger
├── backend # Hono 后端
│ ├── prisma # Prisma schema
│ ├── sql # MySQL 初始化 SQL
│ └── src # 后端源码
├── frontend
│ ├── web # Vite + Vue 3 Web 管理端
│ └── app # Taro + Vue 3 多端应用
├── docs # 项目开发约定
├── docker-compose.yml # MySQL、Redis 编排
└── .env.example # Docker Compose 环境变量示例
基础环境
- Node.js 22+，推荐配合 Corepack 使用 pnpm
- pnpm 11.1.3+
- Docker Desktop 或 Docker Engine + Docker Compose
项目根目录使用 pnpm workspace 统一管理 backend、frontend/web 和
frontend/app。依赖安装和常用脚本都在根目录执行。
开发启动步骤
1. 准备环境变量
Docker Compose 在项目根目录执行时会自动读取 .env。可以从示例文件复制：
cp .env.example .env
Windows PowerShell：
Copy-Item .env.example .env
.env.example 默认把 MySQL 和 Redis 映射到宿主机 3306、6379。
2. 启动 MySQL 和 Redis
docker compose up -d mysql redis
首次启动 MySQL 容器时，Compose 会把 backend/sql/init.sql 挂载到 /docker-entrypoint-initdb.d/01-init.sql，由 MySQL 镜像自动初始化数据库。
如果数据库卷已经存在，初始化 SQL 不会重复执行。需要重建本地数据时可以执行：
docker compose down -v
docker compose up -d mysql redis
docker compose down -v 会删除本地 MySQL 和 Redis 数据卷，请确认不需要保留本地数据后再执行。
3. 安装依赖
pnpm install
4. 启动 Hono 后端
本地开发地址为 http://localhost:3000。
pnpm dev:backend
如果要按 Vercel 本地模拟方式启动，需要先全局安装 Vercel CLI：
pnpm add -g vercel
然后执行：
pnpm dev:backend:vercel
5. 启动 Web 管理端
pnpm dev:web
frontend/web/.env.development 默认配置：
VITE_PORT=80
VITE_APP_BASE_API=/dev-api
Web 开发服务默认地址：
http://localhost:80
开发环境下 frontend/web/vite.config.ts 已默认把 /dev-api 代理到 http://localhost:3000。
如果 80 端口被占用，可以修改 frontend/web/.env.development 中的 VITE_PORT。
6. 启动 App 端，可选
pnpm dev:app:weapp
H5 模式：
pnpm dev:app:h5
frontend/app/config/dev.ts 已默认把 TARO_APP_API_BASE 指向 http://localhost:3000。
部署步骤
Hono 后端和 Web 管理端推荐分别部署到 Vercel 或其他 Node.js/静态托管环境。根目录 Docker Compose 只负责启动 MySQL 和 Redis。
1. 准备生产环境变量
cp .env.example .env
按实际环境修改 .env，至少建议调整：
MYSQL_ROOT_PASSWORD=请替换为强密码
MYSQL_DATABASE=collab_ledger
MYSQL_APP_USERNAME=collab_ledger_app
MYSQL_APP_PASSWORD=请替换为强密码
MYSQL_PORT=13306
REDIS_PASSWORD=请替换为强密码
REDIS_PORT=16379
生产环境建议把 MYSQL_PORT、REDIS_PORT 改成非默认宿主机端口，例如上面的 13306、16379。这两个变量只影响宿主机暴露端口，不影响容器内部端口。
如果数据库和 Redis 只给后端使用，建议进一步通过服务器防火墙限制这些端口的外部访问，或按实际部署需要移除 docker-compose.yml 中 MySQL/Redis 的 ports 暴露配置。
不要提交真实生产 .env 文件。
2. 启动数据库和 Redis
docker compose up -d mysql redis
3. 使用 Vercel CLI 部署后端
先全局安装并登录 Vercel CLI：
pnpm add -g vercel
vercel login
后端作为单独的 Vercel Project 部署，Root Directory 为 backend：
cd backend
vercel link
按提示创建或关联后端项目。然后配置后端环境变量：
vercel env add DATABASE_URL production
vercel env add REDIS_URL production
vercel env add JWT_SECRET production
vercel env add PUBLIC_FILE_BASE_URL production
常见连接串格式：
DATABASE_URL=mysql://user:password@host:3306/collab_ledger
REDIS_URL=redis://:password@host:6379
如果 Redis 服务要求 TLS，使用 rediss://。Vercel Functions 不能连接本机 127.0.0.1、localhost 或 Docker 内网地址，MySQL 和 Redis 必须使用 Vercel 能访问的公网或托管服务地址。
部署后端：
vercel deploy --prod
cd ..
记下部署后的后端域名，例如 https://your-backend.vercel.app。
4. 使用 Vercel CLI 部署 Web 管理端
Web 管理端作为另一个 Vercel Project 部署，Root Directory 为 frontend/web：
cd frontend/web
vercel link
按提示创建或关联 Web 项目。Vercel 识别 Vite 后，构建配置保持：
Install Command: pnpm install
Build Command: pnpm build
Output Directory: dist
配置 Web 指向后端公网地址：
vercel env add VITE_APP_BASE_API production
填入上一步得到的后端域名，例如 https://your-backend.vercel.app。
部署 Web：
vercel deploy --prod
cd ../..
frontend/web/vercel.json 已配置前端路由回退，直接刷新管理端子路由时会返回 index.html。
5. 常用运维命令
查看数据库和 Redis 状态：
docker compose ps
停止服务：
docker compose down
停止并删除数据卷：
docker compose down -v
down -v 会删除数据库和 Redis 数据，生产环境谨慎使用。