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 数据，生产环境谨慎使用。