Merge pull request #49 from DEEIX-AI/dev

chore: updated to version v0.1.2

Author: chenyme

.codex/skills/release-note-writer/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: release-note-writer
+description: Create user-facing GitHub release notes from real git evidence. Use when asked to compare git tags, branches, commits, or version ranges such as v0.1.0...v0.1.1 and draft release notes, changelogs, or bilingual release summaries that emphasize product-visible Features, Optimizations, and Fixes while excluding README-only, version-bump, CI, template, and internal-only noise.
+---
+
+# Release Note Writer
+
+## Overview
+
+Draft release notes from the actual repository diff, not from guesses. Keep the output suitable for a GitHub Release page and focused on what users, admins, operators, or integrators can observe.
+
+## Workflow
+
+1. Confirm the comparison target.
+   - Use the user-provided range exactly when present, for example `v0.1.0...v0.1.1`.
+   - Check that refs exist with `git tag --list`, `git rev-parse`, or `git log --oneline --decorate <range>`.
+   - Inspect worktree state with `git status --short`, but do not include unrelated local dirt in release content unless the user explicitly asks for it.
+
+2. Gather evidence from git.
+   - Start broad: `git log --oneline --decorate <range>`, `git diff --name-status <range>`, and `git diff --stat <range>`.
+   - Read focused diffs for likely product behavior. Prefer files under application, API, route, service, UI, i18n, and shared client layers.
+   - Use `rg` to locate labels, routes, settings, and UI strings that reveal user-facing behavior.
+   - When commit messages and code disagree, trust the code.
+
+3. Filter the content.
+   - Include: new capabilities, changed workflows, admin/user controls, integrations, validation behavior, visible errors, security-relevant behavior users must know, performance or reliability improvements that affect use.
+   - Exclude unless explicitly requested: README/docs-only edits, version bumps, generated docs, CI workflow changes, issue templates, config-example-only edits, tests, refactors with no behavior change, dependency churn, formatting, and internal implementation details.
+   - Collapse several low-level changes into one release-note item when they support the same user-facing outcome.
+
+4. Classify each item.
+   - `Feature`: new or newly exposed product capability.
+   - `Optimization`: improved workflow, behavior, compatibility, validation clarity, reliability, or management experience.
+   - `Fixed`: resolved defect, incorrect behavior, missing error handling, broken display, or mismatch.
+   - If an item could fit multiple sections, choose the section most useful to a release reader.
+
+5. Write in a popular-project release style.
+   - Use short bullets with concrete product nouns.
+   - Use restrained emoji in headings or major bullets only.
+   - Avoid implementation jargon, commit hashes, and file paths unless the user asks for evidence.
+   - Prefer active, user-facing wording: "Added Projects for organizing conversations" instead of "Implemented project APIs".
+   - Keep release-note text concise; do not over-explain.
+
+## Output Format
+
+When the user asks for English plus Chinese, put English first, then a Chinese version. Use exactly these three sections unless the user requests a different structure:
+
+```markdown
+## <version> Release Notes
+
+### ✨ Feature
+- ...
+
+### ⚡ Optimization
+- ...
+
+### 🐛 Fixed
+- ...
+
+---
+
+## <version> 中文版本
+
+### ✨ Feature
+- ...
+
+### ⚡ Optimization
+- ...
+
+### 🐛 Fixed
+- ...
+```
+
+## Quality Checks
+
+- Ensure every bullet is backed by the inspected git range.
+- Ensure no README-only, version-bump, template-only, or config-example-only item appears unless the user explicitly requested it.
+- Ensure Feature, Optimization, and Fixed are all present. If one section has no meaningful user-facing items, include the heading and write `- None.` only if the user requires the section.
+- Ensure the Chinese version matches the English version in meaning, not necessarily word-for-word.
+- Do not run development servers or long-lived services just to draft release notes.
+
+## Example Request
+
+User: "Compare `v0.1.0...v0.1.1`; draft a GitHub Release Note with Feature, Optimization, Fixed sections, English first and Chinese after it."

.codex/skills/release-note-writer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Release Note Writer"
+  short_description: "Draft user-facing GitHub release notes"
+  default_prompt: "Use $release-note-writer to compare a git version range and draft bilingual GitHub release notes."

.github/workflows/commit-message.yml

@@ -25,7 +25,7 @@ jobs:
         run: |
           set -euo pipefail
 
-          pattern='^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test): [A-Za-z0-9 _-]+$'
+          pattern='^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test): [A-Za-z0-9 ._-]+$'
 
           range="${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}"
 
@@ -47,6 +47,6 @@ jobs:
           if [[ "$invalid" -ne 0 ]]; then
             echo "Commit message subjects must use: type: subject"
             echo "Allowed types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test"
-            echo "Allowed subject characters: English letters, numbers, spaces, hyphens, and underscores"
+            echo "Allowed subject characters: English letters, numbers, spaces, periods, hyphens, and underscores"
             exit 1
           fi

CONTRIBUTING.md

@@ -39,7 +39,7 @@ Use the example configuration files for local development. Do not commit local s
 ## Commit Messages
 
 Use the `type: subject` format for every commit message subject.
-Use only English letters, numbers, spaces, hyphens, and underscores in the subject.
+Use only English letters, numbers, spaces, periods, hyphens, and underscores in the subject.
 
 Allowed types:
 

README.md

@@ -111,6 +111,24 @@ If omitted, local development defaults to `localhost:8080`; same-origin deployme
 
 Priority: `environment variables > config.yaml > built-in defaults`.
 
+The Docker image runs from `/app`. With the default compose mount below, the backend reads `/app/config.yaml` automatically:
+
+```yaml
+volumes:
+  - ./config.yaml:/app/config.yaml:ro
+```
+
+To use a different file path, set `CONFIG_FILE` to the container path:
+
+```yaml
+environment:
+  CONFIG_FILE: "/app/config.yaml"
+```
+
+Custom config file paths are read from `CONFIG_FILE`. If both compose environment variables and `config.yaml` define the same key, the environment variable wins. In `docker-compose.full.yml`, `POSTGRES_DSN`, `REDIS_ADDR`, and `REDIS_PASSWORD` are set in `environment`, so they override the PostgreSQL and Redis values in `config.yaml`.
+
+`config.yaml` is for static infrastructure and security configuration such as server URLs, database, Redis, storage, GeoIP, tracing, JWT, and encryption keys. Runtime business settings are stored in the database and managed in the admin console, so changing those values in YAML after startup is not the source of truth.
+
 `APP_ENV` accepts `dev`/`development` and `prod`/`production`, normalizes them to `dev` or `prod`, and defaults to `prod` when omitted. Use `dev` only for local development. Public production deployments should keep `APP_ENV=prod` or `APP_ENV=production` and use production secrets.
 
 #### Lightweight Start
@@ -123,6 +141,8 @@ cp config.docker.example.yaml config.yaml
 docker compose up -d
 ```
 
+This mode primarily uses `config.yaml`; keep compose `environment` empty unless you intentionally want an environment variable to override the file.
+
 #### Full Stack Start
 
 Starts `app`, `postgres`, and `redis`. Use this for local evaluation, development smoke tests, or single-machine deployments without external services.
@@ -132,6 +152,8 @@ cp config.docker.example.yaml config.yaml
 docker compose -f docker-compose.full.yml up -d
 ```
 
+This mode uses compose environment variables for the bundled PostgreSQL and Redis services. Edit `docker-compose.full.yml` or remove those environment entries if you want `config.yaml` to provide these connection values instead.
+
 The default application image is `ghcr.io/deeix-ai/deeix-chat:latest`. Override it with `DEEIX_CHAT_IMAGE` when testing a custom build:
 
 ```bash
@@ -140,6 +162,13 @@ DEEIX_CHAT_IMAGE=deeix-chat:local docker compose up -d --build
 
 Docker URL: `http://localhost:8080`. Keep the Docker `server` section unchanged unless changing ports or public domains; then update compose ports, public URLs, and CORS together.
 
+For troubleshooting, inspect startup logs and verify that the mounted file exists inside the container:
+
+```bash
+docker compose exec app ls -l /app/config.yaml
+docker compose logs app
+```
+
 #### Separated Deployment
 
 Use this mode when the frontend and backend are served from different public origins, for example `https://chat.example.com` and `https://api.example.com`.
@@ -221,6 +250,8 @@ pnpm build
 
 Static infrastructure configuration is loaded from the repository-level `config.yaml` and can be overridden by environment variables. Runtime business settings are stored in `system_settings` and managed from the admin console.
 
+Docker deployments read `/app/config.yaml` by default when `./config.yaml` is mounted to `/app/config.yaml`. `CONFIG_FILE` can point to another container path.
+
 Frontend build-time variables:
 
 | Variable | Purpose |
@@ -232,6 +263,7 @@ Common backend environment variables:
 | Variable | Purpose |
 | --- | --- |
 | `APP_ENV` | Runtime environment. Accepts `dev`/`development` and `prod`/`production`; omitted values default to `prod`. |
+| `CONFIG_FILE` | Optional custom config file path inside the running process or container. Docker defaults to `/app/config.yaml` through the working directory and compose mount. |
 | `HTTP_PORT` | API/runtime port. |
 | `JWT_SECRET` | JWT signing secret. Must be strong in production. |
 | `DATA_ENCRYPTION_KEY` | Key material for encrypted secrets such as upstream API keys, SSO client secrets, MCP tokens, and TOTP secrets. |

README.zh-CN.md

@@ -111,6 +111,24 @@ NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8080
 
 优先级：`环境变量 > config.yaml > 代码内置默认值`。
 
+Docker 镜像工作目录是 `/app`。使用默认 compose 挂载时，后端会自动读取 `/app/config.yaml`：
+
+```yaml
+volumes:
+  - ./config.yaml:/app/config.yaml:ro
+```
+
+如果需要指定其他配置文件路径，使用 `CONFIG_FILE`，值必须是容器内路径：
+
+```yaml
+environment:
+  CONFIG_FILE: "/app/config.yaml"
+```
+
+自定义配置文件路径只读取 `CONFIG_FILE`。如果 compose 的 `environment` 和 `config.yaml` 同时配置同一个键，环境变量优先。`docker-compose.full.yml` 默认在 `environment` 中写入了 `POSTGRES_DSN`、`REDIS_ADDR`、`REDIS_PASSWORD`，因此会覆盖 `config.yaml` 中的 PostgreSQL 和 Redis 配置。
+
+`config.yaml` 只负责静态基础设施和安全配置，例如服务地址、数据库、Redis、存储、GeoIP、Trace、JWT 和加密密钥。运行时业务配置存储在数据库中，并通过后台管理修改；这些配置启动后不以 YAML 为准。
+
 `APP_ENV` 支持 `dev`/`development` 和 `prod`/`production`，内部会规范化为 `dev` 或 `prod`；未配置时默认 `prod`。`dev` 只用于本地开发；公网生产部署应保持 `APP_ENV=prod` 或 `APP_ENV=production` 并使用生产密钥。
 
 #### 轻量启动
@@ -123,6 +141,8 @@ cp config.docker.example.yaml config.yaml
 docker compose up -d
 ```
 
+这种方式主要使用 `config.yaml`。除非明确希望用环境变量覆盖配置文件，否则 compose 中不需要额外写同名 `environment`。
+
 #### 全量启动
 
 启动 `app`、`postgres`、`redis` 三个容器。适合本机试用、开发自测或无外部数据库的单机部署。
@@ -132,6 +152,8 @@ cp config.docker.example.yaml config.yaml
 docker compose -f docker-compose.full.yml up -d
 ```
 
+这种方式会通过 compose 环境变量连接内置 PostgreSQL 和 Redis。如果希望这些连接配置完全来自 `config.yaml`，需要修改 `docker-compose.full.yml` 或删除对应 `environment` 项。
+
 默认应用镜像为 `ghcr.io/deeix-ai/deeix-chat:latest`。测试自定义构建时可通过 `DEEIX_CHAT_IMAGE` 覆盖：
 
 ```bash
@@ -140,6 +162,13 @@ DEEIX_CHAT_IMAGE=deeix-chat:local docker compose up -d --build
 
 Docker 地址：`http://localhost:8080`。除非修改端口或公网域名，否则不要改 Docker 配置里的 `server` 段；如需修改，端口映射、公开 URL 和 CORS 必须一起调整。
 
+排查配置是否挂载成功时，可检查容器内文件和启动日志：
+
+```bash
+docker compose exec app ls -l /app/config.yaml
+docker compose logs app
+```
+
 #### 分离部署
 
 当前端和后端分别暴露在不同公网地址时使用分离部署，例如 `https://chat.example.com` 和 `https://api.example.com`。
@@ -221,6 +250,8 @@ pnpm build
 
 静态基础设施配置从仓库根目录的 `config.yaml` 读取，并支持环境变量覆盖。运行时业务配置存储在 `system_settings`，由后台管理。
 
+Docker 部署默认通过 `./config.yaml:/app/config.yaml:ro` 挂载并读取 `/app/config.yaml`。如需自定义路径，使用 `CONFIG_FILE` 指向容器内路径。
+
 前端构建期变量：
 
 | 变量 | 作用 |
@@ -232,6 +263,7 @@ pnpm build
 | 变量 | 作用 |
 | --- | --- |
 | `APP_ENV` | 运行环境。支持 `dev`/`development` 和 `prod`/`production`；未配置时默认 `prod`。 |
+| `CONFIG_FILE` | 可选的配置文件路径，Docker 场景应填写容器内路径；默认 compose 挂载后会读取 `/app/config.yaml`。 |
 | `HTTP_PORT` | API/运行时端口。 |
 | `JWT_SECRET` | JWT 签名密钥，生产环境必须使用强随机值。 |
 | `DATA_ENCRYPTION_KEY` | 上游 API Key、SSO Client Secret、MCP Token、敏感设置和 TOTP Secret 的加密密钥材料。 |

VERSION

@@ -1 +1 @@
-0.1.1
+0.1.2

backend/README.md

@@ -100,6 +100,19 @@ observability:
 
 `APP_ENV` 未配置时默认 `prod`。`dev`/`development` 只用于本地开发；公网生产部署应保持 `APP_ENV=prod` 或 `APP_ENV=production` 并使用生产密钥。
 
+## 邮箱注册 Turnstile
+
+邮箱注册可选启用 Cloudflare Turnstile 人机验证，作用范围仅限邮箱注册；OAuth/OIDC 登录或注册不需要 Turnstile 校验。
+
+相关运行时设置：
+
+- `auth:turnstile_registration_enabled`：是否在邮箱注册时启用 Turnstile。
+- `auth:turnstile_site_key`：前端渲染 Turnstile 组件使用的 Site Key，会通过 `/api/v1/auth/login-options` 返回。
+- `auth:turnstile_secret_key`：后端调用 Cloudflare siteverify 使用的 Secret Key，属于敏感设置。
+- `TURNSTILE_SITEVERIFY_URL` / `security.turnstile_siteverify_url`：可选覆盖 siteverify 端点，默认使用 Cloudflare 官方地址。
+
+启用 Turnstile 需要同时启用 `auth:email_registration_enabled`，并配置 Site Key 与 Secret Key。开启邮箱验证码注册时，前端在 `/api/v1/auth/register/email/start` 提交 `turnstileToken`；关闭邮箱验证码但允许邮箱注册时，前端在 `/api/v1/auth/register/email/complete` 提交 `turnstileToken`。
+
 生产环境安全校验：
 
 - `APP_ENV` 支持 `dev`/`development` 和 `prod`/`production`，其他值会启动失败。

backend/cmd/server/main.go

@@ -9,7 +9,7 @@ import (
 )
 
 // @title DEEIX Chat API
-// @version 0.1.1
+// @version 0.1.2
 // @description DEEIX Chat 后端 API 文档
 // @BasePath /api/v1
 // @securityDefinitions.apikey BearerAuth