快速开始
OCM = 智慧教室管理系统,三端一体:Go 后端 + 微信小程序 + Web 控制台,外加 MySQL 8。最快的方式是用 docker compose 一键起全栈。
前置
- Docker(推荐用 compose 一键起);或本地装 Go 1.26+、Node ≥ 20.19、MySQL 8。
- 微信开发者工具(仅开发小程序时需要)。
- 仓库根
.env.example:cp .env.example .env,按需填(开发可不填,用默认值;生产必填,见下)。
一键起全栈(推荐)
git clone <repo> ocm && cd ocm
docker compose up -d # mysql + backend(air 热更)+ web(vite)
启动后:
| 服务 | 地址 | 说明 |
|---|---|---|
| Web 控制台 | http://localhost:5173 | 登录用下方默认账号 |
| 后端 API | http://localhost:8080 | /api/...;/healthz、/readyz |
| MySQL | localhost:3306 | 库 ocm / 用户 ocm / 密码 ocm(dev) |
dev compose 用开发默认值:JWT_SECRET 空(后端用开发兜底密钥) 、ADMIN_PASSWORD 空(后端用 admin123)。所以不建 .env 也能跑开发栈;但小程序登录需要 WX_APP_ID/WX_APP_SECRET(见下)。
默认账号:首次启动 users 表为空时种入管理员,用户名 admin,密码 = ADMIN_PASSWORD(开发默认 admin123)。用它在 http://localhost:5173 登录 Web 端。
环境变量(.env)
compose 自动加载仓库根 .env。关键项:
| 变量 | 开发 | 生产 | 说明 |
|---|---|---|---|
JWT_SECRET | 可空(兜底) | 必填 | HS256 签名密钥 |
ADMIN_PASSWORD | 可空(admin123) | 必填 | 种入 admin 的密码 |
WX_APP_ID / WX_APP_SECRET | 仅小程序需要 | 仅小程序需要 | code2Session;web-only 可留空(wx 端点会 502 直到配置) |
MYSQL_ROOT_PASSWORD / DB_PASSWORD | dev 固定 | 必填 | MySQL 密码 |
DB_MAX_OPEN_CONNS / DB_MAX_IDLE_CONNS / DB_CONN_MAX_LIFETIME | 25 / 25 / 5m | 连接池调优 | |
IOT_MQTT_PASSWORD 等 IOT_* | 空 | 物联网数据面；用 IoT overlay 时必填,见物联网 | |
METRICS_ADDR | 未设即关闭 | /metrics 内网监听;用可观测性 overlay 时为 :9091,见可观测性 | |
BRAND_NAME / LOG_LEVEL / LOG_FORMAT | OCM / info / 生产 JSON | 品牌名与日志;详见可观测性 | |
ICP_NUMBER | 可空 | 可空 | 登录页底部备案号(构建期注入) |
DOCS_URL | 可空 | 可空 | 登录页文档链接(设了才显示) |
生产用 docker-compose.prod.yml,对 DB_PASSWORD/MYSQL_ROOT_PASSWORD/JWT_SECRET/ADMIN_PASSWORD 做 fail-fast(缺则拒启)。
各端单独跑
后端(Go)
cd backend
APP_ENV=development go run . # 或 air 热更
需 MySQL 可达(DB_HOST 等默认指向 localhost:3306,dev 凭据 ocm/ocm)。APP_ENV=development 允许 DB_HOST 缺省回落 localhost;生产模式拒绝。
Web 控制台
cd web && npm install && npm run dev # http://localhost:5173
/api 由 Vite 代理到 VITE_API_PROXY_TARGET(默认 http://localhost:8080)。
小程序
- 微信开发者工具打开
miniapp/(不是仓库根)。 2.「工具 → 构建 npm」生成miniprogram_npm/。 - 起后端(:8080)。开发者工具里
envVersion=develop自动走http→http://localhost:8080,无需改配置。 4.「详情 → 本地设置 → 不校验合法域名」放行 localhost;真机把devConfig.baseUrl的localhost换局域网 IP。
详见 小程序。
生产部署
docker compose -f docker-compose.prod.yml --env-file .env up -d
- Web
:80(nginx 单入口,/api代理到内网backend:8080,SPA fallback;后端不发布宿主机端口),mysql 自带。可选叠加监控栈,见可观测性。 - Web 静态站可单独部署到腾讯云 EdgeOne Pages:
web/edgeone.json(SPA 重写)+web/edge-functions/api/边缘函数反代/api到后端(设API_ORIGIN)。详见 Web 端。
健康检查
GET /healthz—— 进程存活(不查 DB,开库前即注册)。GET /readyz—— 就绪(ping DB,不可达 503,开库后注册)。