feat: rebuild xiteng.site homelab platform

2026-08-12 09:48:25 +08:00
parent 557b0eca33
commit 5b84988789
128 changed files with 14979 additions and 292 deletions
@@ -0,0 +1,34 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This repository manages a Docker Compose homelab. The root `compose.yml` defines the shared `homelab_net` network. Each service lives in its own directory with a local Compose file, for example `traefik/compose.yml`, `authentik/compose.yml`, `gitea/compose.yml`, `seaweedfs/compose.yml`, and `chat/compose.yml`. Runtime state and secrets belong in service-local `data/`, `var/`, `letsencrypt/`, `.env`, or similar untracked paths.
+
+`cat-bodhi/` is the main application code: `index.html`, `game.js`, `styles.css`, `server.mjs`, `assets/`, `data/`, and Python sprite tooling under `tools/` and `sprite_alpha_seg_pytorch/`.
+
+## Build, Test, and Development Commands
+
+- `docker compose -f compose.yml up -d`: create or update the shared network.
+- `docker compose -f traefik/compose.yml up -d`: start a service stack; swap the path for other services.
+- `docker compose -f <service>/compose.yml config`: validate a service Compose file before deploying it.
+- `docker compose -f <service>/compose.yml logs -f`: inspect service logs during troubleshooting.
+- `cd cat-bodhi && npm run dev`: run the local game and sprite import server on port `8080`.
+- `cd cat-bodhi && npm run dev:ai:proxy`: run the same server with Node environment proxy support.
+
+## Coding Style & Naming Conventions
+
+Use two-space indentation in YAML, HTML, CSS, and JavaScript. Keep Compose service names, directories, and network aliases lowercase with hyphens, matching paths such as `uptime-kuma` and `outpost-seaweedfs`. Prefer explicit image tags over floating versions. Keep Traefik labels grouped with their service and preserve existing label patterns.
+
+For `cat-bodhi`, keep the vanilla HTML/CSS/JS structure. Name JavaScript functions and variables in `camelCase`; use descriptive asset filenames such as `decor-cat-bed.png`.
+
+## Testing Guidelines
+
+There is no centralized test suite. Validate infrastructure edits with `docker compose -f <service>/compose.yml config` and, when practical, restart only the affected service. For `cat-bodhi`, run `npm run dev`, open `http://localhost:8080`, and manually verify the changed workflow. If sprite processing changes, verify `/api/sprite-status` and `/api/sprite-import`.
+
+## Commit & Pull Request Guidelines
+
+Recent history uses short Conventional Commit-style prefixes such as `feat:`, `fix:`, `docs:`, and `refactor:`, sometimes with Chinese descriptions. Keep commits focused on one service or feature. Pull requests should summarize changed services, include validation commands, call out environment or secret changes, and attach screenshots for UI changes.
+
+## Security & Configuration Tips
+
+Do not commit real `.env` files, tunnel tokens, private keys, certificates, or generated service data. When adding a public route, confirm the intended Authentik mode: app-level OAuth/OIDC or Traefik ForwardAuth. Keep exposed domains and Traefik routers consistent with `README.md`.