Files

T

yuxuanhui 4b42b55928 feat: initialize Ballet Island 微信小程序 with basic structure and functionality

- Add project configuration for WeChat mini program.
- Create skills lock file for Taroify integration.
- Set up app configuration and styles.
- Implement main app component and index page with welcome message.
- Add health check service to verify backend readiness.
- Configure TypeScript settings and global types.

2026-09-28 13:41:48 +08:00

5.0 KiB

Raw Blame History

Ballet Island

同一 Git 仓库中的两个独立项目，分别安装依赖、运行与构建。当前提供项目骨架、欢迎页和服务健康检查，业务需求后续补充。

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，以及具有该小程序开发权限的微信开发者工具。

从仓库根目录进入小程序项目：

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/ 中通过构建时环境变量指定接口地址，修改后重启构建：

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。

另开终端，从仓库根目录进入后端项目：

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/ 中执行：

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 数据卷按官方镜像说明挂载到 /var/lib/postgresql。已有数据库卷的密码不会因修改 .env 自动更新；需按数据库流程修改，不要为更新密码删除数据卷。

验证与构建

在 miniprogram/ 中：

pnpm typecheck
pnpm build

在 backend/ 中：

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 时停止接收请求并关闭连接池。

5.0 KiB Raw Blame History Unescape Escape