117 lines
5.0 KiB
Markdown
117 lines
5.0 KiB
Markdown
|
# Ballet Island
|
|||
|
|
|
|||
|
|
同一 Git 仓库中的两个独立项目，分别安装依赖、运行与构建。当前提供项目骨架、欢迎页和服务健康检查，业务需求后续补充。
|
|||
|
|
|
|||
|
|
## 目录
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
miniprogram/ Taro 4.2.1 + React 18 + TypeScript + Taroify 1.0.6
|
|||
|
|
src/ 小程序源码
|
|||
|
|
config/ 小程序构建配置
|
|||
|
|
package.json 小程序依赖与命令
|
|||
|
|
pnpm-lock.yaml 小程序依赖锁文件
|
|||
|
|
node_modules/ 小程序本地依赖（不提交）
|
|||
|
|
.nvmrc Node 版本
|
|||
|
|
.agents/skills/taroify/ Taroify Agent Skill
|
|||
|
|
backend/ Go 1.26 + PostgreSQL 18
|
|||
|
|
cmd/server/ 服务入口、数据库连接与优雅退出
|
|||
|
|
internal/httpapi/ HTTP 路由与测试
|
|||
|
|
go.mod / go.sum Go 模块与依赖
|
|||
|
|
Dockerfile 后端镜像构建
|
|||
|
|
compose.yaml API 与数据库编排
|
|||
|
|
.env.example 后端环境变量示例
|
|||
|
|
scripts/dev.sh 本机 Go 开发启动脚本
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
小程序的 Node、pnpm 配置和依赖均位于 `miniprogram/`。后端通过 Go、Docker 和 shell 独立运行。根目录保留 Git、说明文档和通用仓库约定。
|
|||
|
|
|
|||
|
|
## 小程序开发
|
|||
|
|
|
|||
|
|
需要 Node.js 22.12+（`miniprogram/.nvmrc` 指定 22.22.1）、pnpm 9.15.0，以及具有该小程序开发权限的微信开发者工具。
|
|||
|
|
|
|||
|
|
从仓库根目录进入小程序项目：
|
|||
|
|
|
|||
|
|
```sh
|
|||
|
|
cd miniprogram
|
|||
|
|
pnpm install --frozen-lockfile
|
|||
|
|
pnpm dev
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
微信开发者工具导入 `miniprogram/`，AppID 为 `wx6dfbf1021db8aee0`，编译目录为 `dist/`。首页“检查连接”请求后端 `/readyz`，同时检查数据库是否可用。
|
|||
|
|
|
|||
|
|
默认 API 为 `http://127.0.0.1:8080`。使用本地 HTTP 地址时，在开发者工具的本地设置中开启“不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书”，仅用于本地调试。真机需使用能够访问的接口地址，并按微信要求配置域名。
|
|||
|
|
|
|||
|
|
在 `miniprogram/` 中通过构建时环境变量指定接口地址，修改后重启构建：
|
|||
|
|
|
|||
|
|
```sh
|
|||
|
|
TARO_APP_API_BASE_URL=https://api.example.com pnpm dev
|
|||
|
|
TARO_APP_API_BASE_URL=https://api.example.com pnpm build
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`TARO_APP_API_BASE_URL` 是公开接口地址，不自动读取后端 `.env`；未设置时使用本机默认地址。
|
|||
|
|
|
|||
|
|
## 后端开发
|
|||
|
|
|
|||
|
|
需要 Go 1.26 或更高版本，以及 Docker Compose。仅使用 Docker 运行后端时无需本机 Go。
|
|||
|
|
|
|||
|
|
另开终端，从仓库根目录进入后端项目：
|
|||
|
|
|
|||
|
|
```sh
|
|||
|
|
cd backend
|
|||
|
|
test -f .env || cp .env.example .env
|
|||
|
|
docker compose up -d --wait postgres
|
|||
|
|
./scripts/dev.sh
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`backend/.env` 已被 Git 忽略。启动脚本读取其中的 PostgreSQL 标准 `PG*` 变量与 `HTTP_ADDR`，先构建再启动 Go 服务；修改代码后需重启命令。脚本只应读取可信的本地配置，`.env` 使用 shell 赋值语法，含空格或 `$` 等特殊字符的值须用单引号包裹。直接运行 Go 或二进制时需自行注入环境变量。
|
|||
|
|
|
|||
|
|
后端全程无需 Node.js 或 pnpm。
|
|||
|
|
|
|||
|
|
## Docker 运行与部署
|
|||
|
|
|
|||
|
|
以下命令在 `backend/` 中执行：
|
|||
|
|
|
|||
|
|
```sh
|
|||
|
|
docker compose up -d --build --wait
|
|||
|
|
curl http://127.0.0.1:8080/healthz
|
|||
|
|
curl http://127.0.0.1:8080/readyz
|
|||
|
|
docker compose logs -f
|
|||
|
|
docker compose down
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Compose 等待数据库健康后启动 API，并等待两个服务就绪。API 容器使用非 root 用户；数据库写入命名卷，`docker compose down` 保留数据。Compose 项目名固定为 `ballet-island`，沿用现有数据库卷。
|
|||
|
|
|
|||
|
|
默认仅向宿主机回环地址开放 API 和数据库。部署到服务器时，可让 HTTPS 反向代理连接 `127.0.0.1:${API_PORT}`；如确需其他机器直接访问 API，可在 `backend/.env` 调整 `API_BIND`。数据库端口始终只绑定本机。Compose 内部使用 `PGHOST=postgres`、`PGPORT=5432`，宿主机数据库端口由 `.env` 的 `PGPORT` 控制。
|
|||
|
|
|
|||
|
|
`API_PORT` 控制 Docker API 的宿主机端口，`HTTP_ADDR` 控制本机 Go 服务的监听地址；修改后应同步小程序的 API 地址。本机 Go 服务与 Docker API 不应同时占用同一端口。
|
|||
|
|
|
|||
|
|
正式上线需配置 HTTPS、微信 request 合法域名、环境密码与数据库备份。小程序由微信开发者工具发布，Docker 部署后端和数据库。
|
|||
|
|
|
|||
|
|
PostgreSQL 18 数据卷按[官方镜像说明](https://hub.docker.com/_/postgres)挂载到 `/var/lib/postgresql`。已有数据库卷的密码不会因修改 `.env` 自动更新；需按数据库流程修改，不要为更新密码删除数据卷。
|
|||
|
|
|
|||
|
|
## 验证与构建
|
|||
|
|
|
|||
|
|
在 `miniprogram/` 中：
|
|||
|
|
|
|||
|
|
```sh
|
|||
|
|
pnpm typecheck
|
|||
|
|
pnpm build
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
在 `backend/` 中：
|
|||
|
|
|
|||
|
|
```sh
|
|||
|
|
go vet ./...
|
|||
|
|
go test -race ./...
|
|||
|
|
go build -o bin/api ./cmd/server
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
产物分别在 `miniprogram/dist/` 和 `backend/bin/api`，均不进入版本控制。
|
|||
|
|
|
|||
|
|
| 接口 | 用途 | 响应 |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| `GET /healthz` | HTTP 服务存活检查 | `200 {"status":"ok"}` |
|
|||
|
|
| `GET /readyz` | 实际检查 PostgreSQL 连接 | 可用时 200，不可用时 `503 {"status":"unavailable"}` |
|
|||
|
|
|
|||
|
|
Go 服务启动时检查数据库连接，收到 `SIGINT` / `SIGTERM` 时停止接收请求并关闭连接池。
|