提交文档站修改

Author: BaronChain

.gitignore

@@ -120,6 +120,9 @@ backend/config.yaml
 deploy/config.yaml
 backend/.installed
 
+# 服务器 SSH 连接信息（含私钥路径等敏感信息）
+SERVER_INFO.md
+
 # ===================
 # 其他
 # ===================

AGENT.md

@@ -158,6 +158,18 @@
 | 改后台/用户页面 | `frontend/src/views/{admin,user}/` + 对应 `api/` + `stores/` |
 | 部署 / Docker | `deploy/` + `docs/部署指南.md` |
 | 本地预览 / 增量推送服务器 | `scripts/deploy-local/` + `docs/本地开发与增量部署指南.md` |
+| 文档站（docs.freecode.codes） | `docs-site/`（VuePress 2 + Theme Hope） |
+
+---
+
+## 7. 服务器 SSH 操作（必读）
+
+> **所有涉及 SSH / 服务器操作的任务，必须先读取 `SERVER_INFO.md` 获取连接信息（IP、端口、用户、私钥路径）。**
+> 该文件已被 `.gitignore` 排除，不会入库。
+
+- SSH 命令模板：`ssh -i ~/.ssh/id_ed25519 root@47.84.98.213 '<命令>'`
+- 文档站静态文件部署在 `/var/www/docs.freecode.codes/`，反代由 Caddy 管理（`/etc/caddy/Caddyfile`）。
+- 文档站更新流程：`cd docs-site && pnpm docs:build` → tar 管道上传到 `/var/www/docs.freecode.codes/`。
 
 ---
 

docs-site/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+src/.vuepress/.cache/
+src/.vuepress/.temp/
+src/.vuepress/dist/
+*.log
+.DS_Store

docs-site/README.md

@@ -0,0 +1,54 @@
+# FreeCode 文档站
+
+基于 VuePress 2 + Theme Hope 的 FreeCode 使用文档站，内容覆盖普通用户教程、API 接入、CLI 配置、第三方客户端、部署运维、管理后台、支付和合规说明。
+
+## 环境要求
+
+- Node.js 18+（已在 Node 24 验证）
+- pnpm（可用 `corepack enable` 启用）
+
+## 常用命令
+
+```bash
+pnpm install        # 安装依赖
+pnpm docs:dev       # 本地开发预览（默认 http://127.0.0.1:8080）
+pnpm docs:build     # 构建静态产物到 src/.vuepress/dist
+pnpm docs:clean-dev # 清缓存后启动开发
+```
+
+## 目录结构
+
+```text
+src/
+├── README.md                  # 站点首页
+├── .vuepress/
+│   ├── config.ts              # 主配置
+│   ├── theme.ts               # Theme Hope 主题配置
+│   ├── navbar.ts              # 顶部导航
+│   ├── sidebar.ts             # 侧边栏
+│   └── public/                # 静态资源
+docs/
+├── register/   # 快速开始
+├── user/       # 用户中心、API 令牌、用量、订单、渠道
+├── token/      # 模型分组介绍
+├── api/        # API 接入与错误排查
+├── ccswitch/   # CC-Switch 使用
+├── cli/        # CLI 配置教程
+├── paint/      # 绘图模型教程
+├── advanced/   # 第三方接入
+├── deploy/     # 部署运维
+├── admin/      # 管理后台
+├── faq/        # 常见问题
+└── tos/        # 条款与政策
+```
+
+## 内容维护原则
+
+- 面向公开用户的内容不要包含服务器私钥、真实 token、OAuth secret、支付密钥或内部账号凭据。
+- API Key、令牌、密钥在用户文档中统一解释为同一类访问凭据，标题尽量使用“API 令牌”。
+- 部署和管理文档以摘要和操作入口为主，敏感部署细节保留在仓库私有文档或服务器私有配置中。
+- 修改文档后运行 `pnpm docs:build`，确认 VuePress 能成功生成静态产物。
+
+## 部署
+
+`pnpm docs:build` 后，将 `src/.vuepress/dist` 中的静态文件部署到文档站 Web 根目录。

docs-site/deploy.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# =============================================================================
+# 文档站一键发布脚本
+# 用法: cd docs-site && bash deploy.sh
+# 功能: 本地构建 → 上传服务器 → 验证
+# =============================================================================
+set -euo pipefail
+
+# ── 配置 ──────────────────────────────────────────────
+REMOTE_HOST="47.84.98.213"
+REMOTE_USER="root"
+SSH_KEY="$HOME/.ssh/id_ed25519"
+REMOTE_DIR="/var/www/docs.freecode.codes"
+SITE_URL="https://docs.freecode.codes"
+# ─────────────────────────────────────────────────────
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+cd "$SCRIPT_DIR"
+
+echo "▶ 构建文档站..."
+pnpm docs:build 2>&1 | grep -vE "INVALID_ANNOTATION|comment ignored|Help:.*pure" || true
+
+DIST="src/.vuepress/dist"
+if [ ! -d "$DIST" ]; then
+  echo "❌ 构建产物目录不存在: $DIST"
+  exit 1
+fi
+
+PAGE_COUNT=$(find "$DIST" -name "*.html" | wc -l)
+SIZE=$(du -sh "$DIST" | cut -f1)
+echo "✅ 构建完成: ${PAGE_COUNT} 个页面, ${SIZE}"
+
+echo "▶ 上传到服务器 ${REMOTE_HOST}:${REMOTE_DIR} ..."
+tar czf - -C "$DIST" . | \
+  ssh -i "$SSH_KEY" -o StrictHostKeyChecking=accept-new "${REMOTE_USER}@${REMOTE_HOST}" \
+    "rm -rf ${REMOTE_DIR}/* && cd ${REMOTE_DIR} && tar xzf - && chown -R www-data:www-data ${REMOTE_DIR} && chmod -R 755 ${REMOTE_DIR}"
+echo "✅ 上传完成"
+
+echo "▶ 验证线上..."
+sleep 1
+HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout 10 "$SITE_URL/" 2>/dev/null || echo "000")
+if [ "$HTTP_CODE" = "200" ]; then
+  echo "✅ 发布成功! $SITE_URL (HTTP $HTTP_CODE)"
+else
+  echo "⚠️  线上验证返回 HTTP $HTTP_CODE（可能是 Cloudflare 缓存延迟，稍后再试）"
+fi

docs-site/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "freecode-docs",
+  "version": "1.0.0",
+  "description": "FreeCode 使用文档站",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "docs:dev": "vuepress dev src",
+    "docs:build": "vuepress build src",
+    "docs:clean-dev": "vuepress dev src --clean-cache"
+  },
+  "devDependencies": {
+    "@vuepress/bundler-vite": "2.0.0-rc.28",
+    "@vuepress/plugin-slimsearch": "2.0.0-rc.128",
+    "sass-embedded": "^1.80.0",
+    "vue": "^3.5.0",
+    "vuepress": "2.0.0-rc.28",
+    "vuepress-theme-hope": "2.0.0-rc.106"
+  }
+}