termi-blog

Monorepo for the Termi blog system.

Structure

.
├─ admin/      # React + shadcn admin workspace
├─ frontend/   # Astro blog frontend
├─ backend/    # Loco.rs backend APIs
├─ mcp-server/ # Streamable HTTP MCP server for articles/categories/tags
├─ deploy/     # Deployment manifests (docker compose/env examples)
├─ .codex/     # Codex workspace config
└─ .vscode/    # Editor workspace config

Run

Recommended

From the repository root:

pnpm dev

This starts frontend + admin + backend in a single Windows Terminal window with multiple tabs.

Common shortcuts:

pnpm dev:mcp
pnpm dev:frontend
pnpm dev:admin
pnpm dev:backend
pnpm dev:mcp-only
pnpm stop
pnpm restart
pnpm test:ui

PowerShell entrypoint

If you prefer direct scripts, use the single root entrypoint:

.\dev.ps1
.\dev.ps1 -WithMcp
.\dev.ps1 -Only frontend
.\dev.ps1 -Only admin
.\dev.ps1 -Only backend
.\dev.ps1 -Only mcp

If you want a single service to be opened as a new Windows Terminal tab instead of running in the current shell:

.\dev.ps1 -Only frontend -Spawn

Legacy aliases are still available and now just forward to dev.ps1:

.\start-frontend.ps1
.\start-backend.ps1
.\start-admin.ps1
.\start-mcp.ps1

Frontend

cd frontend
pnpm install
pnpm dev

Admin

cd admin
pnpm install
pnpm dev

Backend

cd backend
$env:DATABASE_URL="postgres://postgres:postgres%402025%21@10.0.0.2:5432/termi-api_development"
cargo loco start 2>&1

Docker（生产部署，使用 Gitea Package 镜像）

补充部署分层与反代说明见：

• deploy/docker/ARCHITECTURE.md
• deploy/caddy/Caddyfile.tohka.example

docker compose -f deploy/docker/compose.package.yml --env-file deploy/docker/.env up -d

当前 compose 默认启动：

• frontend: http://127.0.0.1:4321
• admin: http://127.0.0.1:4322
• backend api: http://127.0.0.1:5150

注意：deploy/docker/compose.package.yml 不内置 postgres/redis，需使用外部数据库与 Redis。

如果你不是直接用默认端口直连，而是走独立域名 / HTTPS / 反向代理，建议同时设置这些 compose 运行时变量：

• INTERNAL_API_BASE_URL=http://backend:5150/api
• PUBLIC_API_BASE_URL=https://api.blog.init.cool
• PUBLIC_IMAGE_ALLOWED_HOSTS=cdn.example.com,pub-xxxx.r2.dev
• ADMIN_API_BASE_URL=https://admin.blog.init.cool
• ADMIN_FRONTEND_BASE_URL=https://blog.init.cool

可复制 deploy/docker/.env.example 为 deploy/docker/.env 后，至少设置：

• DATABASE_URL
• REDIS_URL
• JWT_SECRET

如需覆盖镜像 tag：

$env:BACKEND_IMAGE="git.init.cool/<owner>/termi-astro-backend:latest"
$env:FRONTEND_IMAGE="git.init.cool/<owner>/termi-astro-frontend:latest"
$env:ADMIN_IMAGE="git.init.cool/<owner>/termi-astro-admin:latest"
docker compose -f deploy/docker/compose.package.yml --env-file deploy/docker/.env up -d

Gitea Actions Docker 发布

仓库已新增：.gitea/workflows/backend-docker.yml

需要在仓库里配置：

• Secrets
  • REGISTRY_USERNAME
  • REGISTRY_TOKEN
  • INDEXNOW_KEY（可选；如果要在主分支镜像发布后自动提交 IndexNow）
• Variables（可选）
  • REGISTRY_HOST（默认 git.init.cool）
  • IMAGE_NAMESPACE（默认仓库 owner）
  • BACKEND_IMAGE_NAME（默认 termi-astro-backend）
  • FRONTEND_IMAGE_NAME（默认 termi-astro-frontend）
  • ADMIN_IMAGE_NAME（默认 termi-astro-admin）
  • FRONTEND_PUBLIC_API_BASE_URL（frontend 镜像构建注入的浏览器侧 API 默认地址，默认 http://localhost:5150/api；运行时推荐优先使用 PUBLIC_API_BASE_URL）
  • ADMIN_VITE_API_BASE（admin 镜像构建注入的 API 默认地址，默认 http://localhost:5150；运行时可被 ADMIN_API_BASE_URL 覆盖）
  • ADMIN_VITE_FRONTEND_BASE_URL（admin 镜像构建注入的前台跳转默认基址，默认 http://localhost:4321；运行时可被 ADMIN_FRONTEND_BASE_URL 覆盖）
  • ADMIN_VITE_BASENAME（可选；如果 admin 要挂在 /admin 这类路径前缀下，构建时设置为 /admin）
  • INDEXNOW_SITE_URL（可选；自动提交 IndexNow 时使用的前台 canonical 域名，例如 https://blog.init.cool）
  • INDEXNOW_PUBLIC_API_BASE_URL（可选；如果站点公开 API 不是 ${INDEXNOW_SITE_URL}/api，可在这里显式指定）

如果同时配置了 INDEXNOW_KEY + INDEXNOW_SITE_URL，主分支镜像发布成功后会自动执行一次：

pnpm --dir frontend run indexnow:submit

用来把首页、文章、分类、标签、评测等 canonical URL 提交到 IndexNow。

MCP Server

.\dev.ps1 -Only mcp

Default MCP endpoint:

http://127.0.0.1:5151/mcp

Default local development API key:

termi-mcp-local-dev-key

The MCP server wraps real backend APIs for:

• Listing, reading, creating, updating, and deleting Markdown posts
• Listing, creating, updating, and deleting categories
• Listing, creating, updating, and deleting tags
• Reading and updating public site settings
• Rebuilding the AI index

Repo Name

Recommended repository name: termi-blog