update dev kit

.gitignore

@@ -63,7 +63,10 @@ next-env.d.ts
 !/data/README.md
 
 # dev tools (local development utilities)
-/dev/
+# Keep the dev toolchain in repo; ignore local-only overrides.
+/dev/.env
+/dev/.env.*
+!/dev/.env.example
 
 # translation checklists and temporary docs
 TRANSLATIONS_CHECKLIST.txt

Makefile

@@ -5,7 +5,7 @@
 # 这个 Makefile 将命令转发到 dev/Makefile
 # 可以在项目根目录直接执行 make 命令
 
-.PHONY: help dev-help dev db app build compose clean migrate db-shell redis-shell logs logs-app logs-db logs-redis reset status stop
+.PHONY: help dev-help dev db app build build-nocache app-rebuild app-nocache prune-images rm-app-image compose clean migrate db-shell redis-shell logs logs-app logs-db logs-redis reset status stop
 
 # 默认目标：显示 dev 工具帮助
 .DEFAULT_GOAL := dev-help
@@ -15,5 +15,5 @@ dev-help:
 	@cd dev && $(MAKE) help
 
 # 转发所有命令到 dev/Makefile
-dev db app build compose clean migrate db-shell redis-shell logs logs-app logs-db logs-redis reset status stop:
+dev db app build build-nocache app-rebuild app-nocache prune-images rm-app-image compose clean migrate db-shell redis-shell logs logs-app logs-db logs-redis reset status stop:
 	@cd dev && $(MAKE) $@

dev/Makefile

@@ -0,0 +1,140 @@
+# ================================
+# Claude Code Hub - dev 工具链
+# ================================
+#
+# 目标:
+# 1) 通过 Docker 启动 PostgreSQL + Redis（供本机 bun dev 使用）
+# 2) 通过 Docker 本地构建 app 镜像并联动 DB/Redis（无需预构建镜像）
+#
+# 说明:
+# - 在项目根目录可直接运行 `make <target>`（根 Makefile 会转发到此处）
+# - 可通过环境变量覆盖端口/账号等（见 help）
+
+.PHONY: help dev db app build build-nocache app-rebuild app-nocache prune-images rm-app-image compose clean migrate db-shell redis-shell logs logs-app logs-db logs-redis reset status stop
+
+PROJECT_NAME ?= cch-dev
+COMPOSE_FILE ?= docker-compose.yaml
+COMPOSE := docker compose -f $(COMPOSE_FILE) -p $(PROJECT_NAME)
+
+# -------- 可配置项（均可通过环境变量覆盖） --------
+export DB_USER ?= postgres
+export DB_PASSWORD ?= postgres
+export DB_NAME ?= claude_code_hub
+export POSTGRES_PORT ?= 5432
+export REDIS_PORT ?= 6379
+export APP_PORT ?= 23000
+export ADMIN_TOKEN ?= cch-dev-admin
+export APP_VERSION ?= dev
+export ENABLE_RATE_LIMIT ?= true
+
+POSTGRES_HOST ?= 127.0.0.1
+REDIS_HOST ?= 127.0.0.1
+
+LOCAL_DSN ?= postgres://$(DB_USER):$(DB_PASSWORD)@$(POSTGRES_HOST):$(POSTGRES_PORT)/$(DB_NAME)
+LOCAL_REDIS_URL ?= redis://$(REDIS_HOST):$(REDIS_PORT)
+
+help:
+	@echo ""
+	@echo "Claude Code Hub - dev 工具链"
+	@echo ""
+	@echo "常用命令:"
+	@echo "  make db        启动 PostgreSQL + Redis（Docker）"
+	@echo "  make dev       启动 db/redis 后运行 bun dev（连接 Docker db/redis）"
+	@echo "  make app       本地构建并启动 app 镜像 + db + redis（无需预构建镜像）"
+	@echo "  make build     仅本地构建 app 镜像"
+	@echo "  make app-rebuild 强制重建并重建容器（适合代码改动后确保生效）"
+	@echo "  make app-nocache 无缓存重建 app 镜像并重建容器（排查构建缓存问题）"
+	@echo "  make prune-images 清理悬空(dangling)镜像（解决多次构建残留）"
+	@echo "  make rm-app-image 删除本地 app 镜像标签（claude-code-hub-local:*)"
+	@echo "  make logs      查看所有服务日志"
+	@echo "  make status    查看容器状态"
+	@echo "  make clean     停止并删除容器（保留数据）"
+	@echo "  make reset     停止并删除容器与数据（危险操作）"
+	@echo ""
+	@echo "可覆盖环境变量:"
+	@echo "  PROJECT_NAME=$(PROJECT_NAME)"
+	@echo "  DB_USER=$(DB_USER) DB_PASSWORD=$(DB_PASSWORD) DB_NAME=$(DB_NAME)"
+	@echo "  POSTGRES_PORT=$(POSTGRES_PORT) REDIS_PORT=$(REDIS_PORT) APP_PORT=$(APP_PORT)"
+	@echo "  ADMIN_TOKEN=$(ADMIN_TOKEN) APP_VERSION=$(APP_VERSION) ENABLE_RATE_LIMIT=$(ENABLE_RATE_LIMIT)"
+	@echo ""
+	@echo "本机 dev 默认连接串:"
+	@echo "  DSN=$(LOCAL_DSN)"
+	@echo "  REDIS_URL=$(LOCAL_REDIS_URL)"
+	@echo ""
+
+db:
+	@$(COMPOSE) up -d postgres redis
+	@$(COMPOSE) ps
+
+dev: db
+	@echo ""
+	@echo "Running bun dev with:"
+	@echo "  DSN=$(LOCAL_DSN)"
+	@echo "  REDIS_URL=$(LOCAL_REDIS_URL)"
+	@echo ""
+	@DSN="$(LOCAL_DSN)" REDIS_URL="$(LOCAL_REDIS_URL)" ENABLE_RATE_LIMIT="$(ENABLE_RATE_LIMIT)" \
+		ADMIN_TOKEN="$(ADMIN_TOKEN)" bun run dev
+
+build:
+	@$(COMPOSE) --profile app build app
+
+build-nocache:
+	@$(COMPOSE) --profile app build --no-cache app
+
+app:
+	@$(COMPOSE) --profile app up -d --build
+	@$(COMPOSE) ps
+	@echo ""
+	@echo "App is starting. Visit: http://localhost:$(APP_PORT)"
+	@echo ""
+
+app-rebuild:
+	@$(COMPOSE) --profile app up -d --build --force-recreate
+	@$(COMPOSE) ps
+
+app-nocache:
+	@$(MAKE) build-nocache
+	@$(MAKE) app-rebuild
+
+prune-images:
+	@docker image prune -f
+
+rm-app-image:
+	@docker image rm -f "claude-code-hub-local:$(APP_VERSION)" 2>/dev/null || true
+
+migrate: db
+	@DSN="$(LOCAL_DSN)" bun run db:migrate
+
+db-shell: db
+	@$(COMPOSE) exec postgres psql -U "$(DB_USER)" -d "$(DB_NAME)"
+
+redis-shell: db
+	@$(COMPOSE) exec redis redis-cli
+
+logs:
+	@$(COMPOSE) logs -f --tail=200
+
+logs-app:
+	@$(COMPOSE) --profile app logs -f --tail=200 app
+
+logs-db:
+	@$(COMPOSE) logs -f --tail=200 postgres
+
+logs-redis:
+	@$(COMPOSE) logs -f --tail=200 redis
+
+status:
+	@$(COMPOSE) ps
+
+stop:
+	@$(COMPOSE) stop
+
+clean:
+	@$(COMPOSE) down --remove-orphans
+
+reset:
+	@$(COMPOSE) down -v --remove-orphans
+	@rm -rf ../data/postgres-dev ../data/redis-dev
+
+compose:
+	@echo "$(COMPOSE)"

dev/README.md

@@ -0,0 +1,49 @@
+# 本地开发（dev 工具链）
+
+本目录提供两种本地开发方式，均使用 Docker 启动的 PostgreSQL + Redis：
+
+1) 本机运行 `bun run dev`，数据库与 Redis 由 Docker 提供
+2) Docker 本地构建并运行 app 镜像（无需预构建镜像），数据库与 Redis 由同一 Compose 提供
+
+## 快速开始
+
+在项目根目录执行（根目录 Makefile 会自动转发到 `dev/`）：
+
+- 启动 DB/Redis（暴露到本机端口，供本机 bun dev 访问）：
+  - `make db`
+- 启动 DB/Redis 后运行本机开发服务器（Next dev，端口 13500）：
+  - `make dev`
+- 本地构建并启动 Docker app（默认端口 23000）：
+  - `make app`
+
+如果你希望手动运行（不通过 `make dev`）：
+
+- 先启动 DB/Redis：`make db`
+- 再启动开发服务器：
+  - `DSN=postgres://postgres:[email protected]:5432/claude_code_hub REDIS_URL=redis://127.0.0.1:6379 ENABLE_RATE_LIMIT=true bun run dev`
+
+## 关于“旧镜像残留”
+
+- `make app` 使用固定标签 `claude-code-hub-local:${APP_VERSION}`，每次 `--build` 会把标签指向新镜像；旧镜像会变成 dangling（不影响运行，但会占用磁盘）。
+- 常用处理：
+  - 强制重建并重建容器：`make app-rebuild`
+  - 无缓存重建：`make app-nocache`
+  - 清理 dangling 镜像：`make prune-images`
+
+## 常用命令
+
+- 查看容器状态：`make status`
+- 查看日志：`make logs` / `make logs-app` / `make logs-db` / `make logs-redis`
+- 进入数据库：`make db-shell`
+- 进入 Redis：`make redis-shell`
+- 停止服务：`make stop`
+- 清理容器（保留数据）：`make clean`
+- 重置环境（删除数据）：`make reset`
+
+## 变量覆盖
+
+可通过环境变量覆盖端口与账号（示例）：
+
+- `POSTGRES_PORT=35432 REDIS_PORT=36379 make db`
+- `APP_PORT=24000 make app`
+- `DB_PASSWORD=postgres make dev`

dev/docker-compose.yaml

@@ -0,0 +1,70 @@
+services:
+  postgres:
+    image: postgres:18
+    restart: unless-stopped
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    environment:
+      POSTGRES_USER: ${DB_USER:-postgres}
+      POSTGRES_PASSWORD: ${DB_PASSWORD:-postgres}
+      POSTGRES_DB: ${DB_NAME:-claude_code_hub}
+      PGDATA: /data/pgdata
+      TZ: Asia/Shanghai
+      PGTZ: Asia/Shanghai
+    volumes:
+      - ../data/postgres-dev:/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-postgres} -d ${DB_NAME:-claude_code_hub}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+      start_period: 10s
+
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+    volumes:
+      - ../data/redis-dev:/data
+    command: redis-server --appendonly yes
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 5s
+
+  app:
+    profiles:
+      - app
+    build:
+      context: ..
+      dockerfile: deploy/Dockerfile
+      args:
+        APP_VERSION: ${APP_VERSION:-dev}
+    image: claude-code-hub-local:${APP_VERSION:-dev}
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    environment:
+      NODE_ENV: production
+      DSN: postgresql://${DB_USER:-postgres}:${DB_PASSWORD:-postgres}@postgres:5432/${DB_NAME:-claude_code_hub}
+      REDIS_URL: redis://redis:6379
+      AUTO_MIGRATE: ${AUTO_MIGRATE:-true}
+      ENABLE_RATE_LIMIT: ${ENABLE_RATE_LIMIT:-true}
+      SESSION_TTL: ${SESSION_TTL:-300}
+      ADMIN_TOKEN: ${ADMIN_TOKEN:-cch-dev-admin}
+      TZ: Asia/Shanghai
+    ports:
+      - "${APP_PORT:-23000}:3000"
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:3000/api/actions/health || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 20
+      start_period: 30s
+