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