docs: complete documentation rewrite with 25+ new pages and LLM-friendly files

app/components/home/Hero.tsx

@@ -53,7 +53,7 @@ export function Hero() {
 
           <div className="flex flex-wrap justify-center md:justify-start gap-4 mt-4 md:mt-2 mb-4">
             <Link
-              href="/docs/core"
+              href="/docs/getting-started"
               className={cn(
                 buttonVariants({
                   size: 'lg',

app/layout.config.tsx

@@ -60,13 +60,13 @@ export const baseOptions: BaseLayoutProps = {
     {
       type: 'menu',
       text: '文档',
-      url: '/docs/core',
+      url: '/docs/getting-started',
       items: [
         {
           icon: <BookMarked />,
           text: '使用文档',
           description: '了解 Mix Space 如何使用',
-          url: '/docs/usage',
+          url: '/docs/use',
           menu: {
             className: 'md:row-span-2',
           },
@@ -75,7 +75,7 @@ export const baseOptions: BaseLayoutProps = {
           icon: <Server />,
           text: '后端部署',
           description: '部署 Mix Space 的后端部分',
-          url: '/docs/core',          
+          url: '/docs/deploy',          
           menu: {
             className: 'lg:col-start-2',
           },
@@ -93,7 +93,7 @@ export const baseOptions: BaseLayoutProps = {
           icon: <Pencil />,
           text: '文档撰写',
           description: '了解 Mix Space 的文档撰写规范',
-          url: '/docs/document',
+          url: '/docs/use/writing',
           menu: {
             className: 'lg:col-start-3 lg:row-start-1',
           },
@@ -102,7 +102,7 @@ export const baseOptions: BaseLayoutProps = {
           icon: <Cpu />,
           text: '开发指南',
           description: '了解如何为 Mix Space 开发后端和前端',
-          url: '/docs/development',
+          url: '/docs/develop',
           menu: {
             className: 'lg:col-start-3',
           },

content/docs/configure/account-security.mdx

@@ -0,0 +1,113 @@
+---
+title: 账号与安全
+description: 管理站点所有者信息、API Token、Passkey 和 OAuth 登录
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+
+Mix Space 的账号系统围绕「所有者」概念设计。每个 Mix Space 实例只有一个所有者（Owner），所有者拥有完整的管理权限。
+
+## 所有者信息
+
+登录后台，进入「设定 → 个人信息」页面。你可以设置以下信息：
+
+| 字段 | 说明 |
+|------|------|
+| **昵称** | 显示名称 |
+| **头像** | 头像图片 URL |
+| **邮箱** | 联系邮箱 |
+| **个人介绍** | 一段简短的个人介绍 |
+| **社交链接** | GitHub、Twitter、Bilibili 等社交账号链接 |
+
+这些信息会被前端主题读取并展示在首页的博主信息区域。
+
+## API Token
+
+API Token 是访问 Mix Space API 的凭证。第三方工具（如 Obsidian 插件、API 客户端）需要 Token 才能调用需要认证的 API。
+
+### 管理 Token
+
+进入「设定 → 账号与安全 → API Token」：
+
+| 操作 | 说明 |
+|------|------|
+| **创建 Token** | 设置名称和过期时间，生成新的 Token |
+| **查看 Token** | 创建时显示完整的 Token 值，请妥善保存 |
+| **删除 Token** | 吊销指定 Token，所有使用该 Token 的请求将被拒绝 |
+
+<Callout type="warn">
+Token 仅在创建时显示一次完整值。如果忘记 Token，需要删除后重新创建。请勿将 Token 提交到公开的代码仓库。
+</Callout>
+
+### Token 的用途
+
+- **Obsidian 插件**：配置 API Token 以同步内容
+- **API 客户端**：`@mx-space/api-client` SDK 使用 Token 认证
+- **自动化脚本**：CI/CD 或自定义脚本调用 API
+
+## Passkey（通行密钥）
+
+Mix Space 支持使用 Passkey（WebAuthn）进行无密码登录，更加安全便捷。
+
+### 添加 Passkey
+
+<Steps>
+<Step>
+### 进入账号设置
+
+前往「设定 → 账号与安全 → Passkey」。
+</Step>
+
+<Step>
+### 注册新密钥
+
+点击「添加 Passkey」，浏览器会弹出安全密钥注册窗口。根据设备不同，可能需要：
+- 使用指纹识别（Touch ID / Windows Hello）
+- 使用面部识别
+- 插入硬件安全密钥（如 YubiKey）
+</Step>
+
+<Step>
+### 命名密钥
+
+为 Passkey 设置一个便于识别的名称（如「MacBook Touch ID」），方便管理。
+</Step>
+</Steps>
+
+<Callout type="info">
+Passkey 与设备和浏览器绑定。如果你更换设备，需要在旧设备上仍然可以登录时添加新的 Passkey。
+</Callout>
+
+## OAuth 第三方登录
+
+Mix Space 支持通过 GitHub、Google 等第三方账号登录后台。
+
+### 配置 OAuth
+
+前往「设定 → OAuth」页面。详细配置步骤请参考 [OAuth 2.0 登录](/docs/configure/oauth)。
+
+### 将 OAuth 账号设为所有者
+
+首次通过 OAuth 登录后，需要在「设定 → 账号与安全」中点击「设为所有者」，将该 OAuth 账号与站点所有者身份绑定。
+
+## 安全设置
+
+### 禁用密码登录
+
+如果你已经配置了 Passkey 或 OAuth 登录，可以在「认证安全设置」中禁用密码登录，提高安全性。
+
+<Callout type="warn">
+禁用密码登录前，请确保你至少有一种可用的替代登录方式（Passkey 或 OAuth）。否则你将无法登录后台。
+</Callout>
+
+## 登录会话
+
+在账号与安全页面，你可以查看当前所有活跃的登录会话：
+
+- 设备和浏览器信息
+- 登录 IP 地址
+- 登录时间
+- 当前会话标记
+
+你可以手动结束其他设备的会话。

content/docs/usage/search.mdx → content/docs/configure/algolia.mdx

@@ -1,5 +1,5 @@
 ---
-title: Algolia Search
+title: Algolia 站内搜索
 description: 使用 Algolia 搜索
 ---
 
@@ -75,7 +75,7 @@ Algolia 是一个数据库实时搜索服务，能够提供毫秒级的数据库
 
 ### 后台配置
 
-进入后台，设定->系统->Algolia Search，将“开启 Algolia Search”开关打开，将前面准备的 `IndexName`、`Application ID（AppID）` 和 `Admin API Key（ApiKey）` 填入对应的框中，右上角保存即可。
+进入后台，设定->系统->Algolia Search，将"开启 Algolia Search"开关打开，将前面准备的 `IndexName`、`Application ID（AppID）` 和 `Admin API Key（ApiKey）` 填入对应的框中，右上角保存即可。
 
 <Image 
   src="https://pan.vinua.cn/f/DeGsA/3331ccce7fe57e4bfd87217998223f30.png" 
@@ -84,4 +84,4 @@ Algolia 是一个数据库实时搜索服务，能够提供毫秒级的数据库
   height={600} 
 />
 
-至此，Algolia 搜索的配置就完成了。稍等一会，就可以尝试在主页用 `Ctrl + K` 调用 Algolia* 进行站内搜索了。*
+至此，Algolia 搜索的配置就完成了。稍等一会，就可以尝试在主页用 `Ctrl + K` 调用 Algolia 进行站内搜索了。

content/docs/usage/security.mdx → content/docs/configure/encryption.mdx

@@ -1,6 +1,6 @@
 ---
-title: Key 加密与安全性
-description: 加密你的 MixSpace 
+title: 数据加密
+description: 加密你的 Mix Space
 ---
 
 在 v3.41.0 后续版本，加入了敏感 Key 加密功能。默认为关。

content/docs/configure/environment.mdx

@@ -0,0 +1,56 @@
+---
+title: 环境变量参考
+description: 所有环境变量的完整说明
+---
+
+<Callout type="info">
+  如果你不确定某个变量的作用，保持默认值即可。
+</Callout>
+
+以下环境变量适用于 Mix Space Core 后端服务。Docker 用户在 `docker-compose.yml` 的 `environment` 中设置；源码用户在 `.env` 或 `ecosystem.config.js` 中设置。
+
+## 核心必填
+
+| 变量名 | 说明 | 默认值 | 示例 |
+| --- | --- | --- | --- |
+| `JWT_SECRET` | JWT 签名密钥 | - | `my-secret-key` |
+| `ALLOWED_ORIGINS` | 允许的跨域域名 | - | `example.com,www.example.com` |
+| `SNOWFLAKE_WORKER_ID` | 工作节点 ID（单实例填 1）| - | `1` |
+
+## PostgreSQL 数据库
+
+| 变量名 | 说明 | 默认值 | 示例 |
+| --- | --- | --- | --- |
+| `PG_URL` | 完整连接字符串（推荐）| - | `postgresql://mx:mx@localhost:5432/mx_core` |
+| `PG_HOST` | 数据库地址 | `127.0.0.1` | `localhost` |
+| `PG_PORT` | 端口 | `5432` | `5432` |
+| `PG_USER` | 用户名 | `mx` | `mx` |
+| `PG_PASSWORD` | 密码 | `mx` | `secret` |
+| `PG_DATABASE` | 数据库名 | `mx_core` | `mx_core` |
+| `PG_MAX_POOL_SIZE` | 连接池大小 | `20` | `20` |
+| `PG_SSL` | 启用 SSL | `false` | `true` |
+
+## Redis
+
+| 变量名 | 说明 | 默认值 | 示例 |
+| --- | --- | --- | --- |
+| `REDIS_HOST` | 地址 | `localhost` | `redis` |
+| `REDIS_PORT` | 端口 | `6379` | `6379` |
+| `REDIS_PASSWORD` | 密码 | - | `secret` |
+
+## 安全
+
+| 变量名 | 说明 | 默认值 | 示例 |
+| --- | --- | --- | --- |
+| `ENCRYPT_ENABLE` | 启用加密 | `false` | `true` |
+| `ENCRYPT_KEY` | 加密密钥（64 位 hex）| 自动获取 machine-id | `abc...` |
+
+## 其他
+
+| 变量名 | 说明 | 默认值 | 示例 |
+| --- | --- | --- | --- |
+| `PORT` | 服务端口 | `2333` | `3000` |
+| `TZ` | 时区 | `Asia/Shanghai` | `UTC` |
+| `DISABLE_CACHE` | 禁用 Redis 缓存 | `false` | `false` |
+| `THROTTLE_TTL` | 限流窗口（秒）| `10` | `10` |
+| `THROTTLE_LIMIT` | 限流次数 | `100` | `100` |

content/docs/configure/image-storage.mdx

@@ -0,0 +1,96 @@
+---
+title: 图床与存储
+description: 配置 S3 兼容对象存储作为图床，自定义存储路径与 CDN 加速
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+
+Mix Space 支持将图片和文件存储到 S3 兼容的对象存储服务（如 Cloudflare R2、AWS S3、阿里 OSS、腾讯 COS 等），替代默认的本地存储。
+
+## 配置 S3 图床
+
+<Steps>
+<Step>
+### 进入图床设置
+
+登录后台，前往「设定 → 图床设置」。
+</Step>
+
+<Step>
+### 开启 S3 图床
+
+打开「开启 S3 图床」开关。
+</Step>
+
+<Step>
+### 填写 S3 配置
+
+| 字段 | 说明 |
+|------|------|
+| **S3 服务端点** | S3 兼容服务的 Endpoint（如 `https://<account>.r2.cloudflarestorage.com`） |
+| **Access Key ID** | 访问密钥 ID |
+| **Secret Access Key** | 访问密钥（加密存储） |
+| **Bucket** | 存储桶名称 |
+| **Region** | 地域（Cloudflare R2 填 `auto`） |
+
+</Step>
+
+<Step>
+### 配置自定义域名（推荐）
+
+填写「自定义域名 (CDN)」字段，用于替换默认的 S3 URL。例如你的 CDN 域名是 `cdn.example.com`，则上传后的文件 URL 为 `https://cdn.example.com/{路径}/{文件名}`。
+</Step>
+
+<Step>
+### 设置文件路径前缀（可选）
+
+填写「文件路径前缀」来组织上传的文件。支持占位符：
+
+| 占位符 | 说明 |
+|--------|------|
+| `{Y}` | 年份（4 位） |
+| `{m}` | 月份 |
+| `{d}` | 日期 |
+| `{type}` | 文件类型 |
+| `{md5}` | 随机 MD5 |
+
+示例：`blog/{Y}/{m}/{d}` → 文件上传到 `blog/2024/01/15/` 路径下。
+</Step>
+</Steps>
+
+<Callout type="info">
+开启 S3 图床后，新上传的文件会存储到 S3。之前上传到本地的文件不会自动迁移，但仍然可以正常访问。
+</Callout>
+
+## 常用 S3 服务配置参考
+
+### Cloudflare R2
+
+| 字段 | 值 |
+|------|-----|
+| S3 服务端点 | `https://<account-id>.r2.cloudflarestorage.com` |
+| Region | `auto` |
+| 自定义域名 | R2 绑定的自定义域名或 `r2.dev` 公开访问地址 |
+
+### AWS S3
+
+| 字段 | 值 |
+|------|-----|
+| S3 服务端点 | 留空（使用默认）或区域端点 |
+| Region | 如 `us-east-1`、`ap-southeast-1` |
+| 自定义域名 | CloudFront 分发域名 |
+
+### 阿里 OSS / 腾讯 COS
+
+按照对应服务的 S3 兼容接口文档填写 Endpoint 和 Region 即可。
+
+## 评论图片专用前缀
+
+在「评论图片路径前缀」字段中，可以为读者评论上传的图片设置独立的存储路径前缀。该字段额外支持 `{readerId}` 占位符，按读者 ID 组织目录。
+
+留空则使用默认路径：`comments/{readerId}/{Y}/{m}/{md5}.{ext}`
+
+## 备份到 S3
+
+在「设定 → 备份」中也可以配置 S3 信息，将数据库备份文件同时上传到 S3 存储，实现异地备份。详见 [备份与恢复](/docs/use/backup-restore)。

content/docs/configure/index.mdx

@@ -0,0 +1,44 @@
+---
+title: 功能配置概览
+description: 快速找到你需要的配置文档
+---
+
+import { Card, Cards } from 'fumadocs-ui/components/card';
+
+## 我想实现的功能
+
+| 我想实现... | 查看文档 |
+| --- | --- |
+| 设置第三方登录（GitHub/Google）| [OAuth 2.0](/docs/configure/oauth) |
+| 配置 SEO 和搜索引擎推送 | [SEO 与站点优化](/docs/configure/seo) |
+| 管理 API Token 和 Passkey | [账号与安全](/docs/configure/account-security) |
+| 配置 S3 图床和 CDN | [图床与存储](/docs/configure/image-storage) |
+| 添加站内搜索 | [Algolia Search](/docs/configure/algolia) |
+| 加密敏感配置 | [Key 加密](/docs/configure/encryption) |
+| 了解所有环境变量 | [环境变量参考](/docs/configure/environment) |
+
+## 快速导航
+
+<Cards>
+  <Card title="环境变量参考" href="/docs/configure/environment">
+    查看所有支持的环境变量及其说明
+  </Card>
+  <Card title="SEO 与站点优化" href="/docs/configure/seo">
+    SEO 元数据、Sitemap、RSS、百度/Bing 推送
+  </Card>
+  <Card title="账号与安全" href="/docs/configure/account-security">
+    所有者信息、API Token、Passkey、OAuth 绑定
+  </Card>
+  <Card title="图床与存储" href="/docs/configure/image-storage">
+    S3 对象存储配置、CDN 加速、自定义存储路径
+  </Card>
+  <Card title="OAuth 2.0" href="/docs/configure/oauth">
+    配置 GitHub、Google 等第三方登录
+  </Card>
+  <Card title="Algolia Search" href="/docs/configure/algolia">
+    为站点添加 Algolia 站内搜索
+  </Card>
+  <Card title="Key 加密" href="/docs/configure/encryption">
+    加密数据库中的敏感配置项
+  </Card>
+</Cards>