gao/ljwx-docs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: 初始化 LJWX Docs 文档站点

Browse Source 
## 功能特性
- ✨ VitePress 1.0 框架，支持中英文双语
- 🌐 远程访问支持（0.0.0.0:5555）
- 🎨 专业级代码块样式（圆角阴影、悬浮效果、智能复制）
- 📊 Mermaid 流程图优化（主题色节点、平滑连线）
- 📋 表格美化（渐变表头、行悬浮高亮）
- 🔍 本地搜索功能（Cmd+K 快捷键）
- 🌓 深色模式完美适配
- 💬 Giscus 评论系统集成
- 📱 响应式设计（移动端优化）

## 技术栈
- VitePress 1.0.1
- Vue 3.4.19
- TypeScript
- Express (生产服务器)

## 文档包含
- 知识资产化系统架构设计
- 自动化发布使用指南
- Dify 知识库同步指南
- 快速参考手册

## 部署支持
- Node.js 服务器
- Docker 容器化
- Nginx 静态托管
- Kubernetes 集群部署

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
bruno
2026-01-23 16:06:02 +08:00
co-authored by Claude Sonnet 4.5
commit ec96907fb6
27 changed files with 5014 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.env.example
+11
View File
@@ -0,0 +1,11 @@
# 服务器配置示例
# 复制此文件为 .env 来自定义配置
# 生产服务器端口（默认：5555）
PORT=5555
# 服务器监听地址（默认：0.0.0.0）
HOST=0.0.0.0
# Node 环境（production/development）
NODE_ENV=production
.gitignore
+41
View File
@@ -0,0 +1,41 @@
# Dependencies
node_modules/
package-lock.json
yarn.lock
pnpm-lock.yaml
# Build output
dist/
.vitepress/cache/
.vitepress/dist/
# Environment variables
.env
.env.local
.env.*.local
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
# OS
.DS_Store
Thumbs.db
# Logs
logs/
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Temporary files
.temp/
.cache/
*.tmp
# VitePress
docs/.vitepress/cache
CONFIGURATION.md
+342
View File
@@ -0,0 +1,342 @@
# 配置说明
## ✅ 已完成的优化
### 1. 远程访问配置 🌐
服务器现已配置为允许远程访问：
```bash
# 开发服务器绑定到 0.0.0.0
pnpm dev
# 或
pnpm start
```
**访问地址：**
- 本地：http://localhost:5555
- 局域网：http://[您的IP地址]:5555
**获取您的IP地址：**
```bash
# macOS/Linux
ifconfig | grep "inet " | grep -v 127.0.0.1
# Windows
ipconfig
```
### 2. 专业视觉增强 🎨
#### 代码块增强
- ✨ **圆角阴影**：12px 圆角 + 柔和阴影
- 🎯 **悬浮效果**：鼠标悬停时轻微上浮
- 📝 **行号优化**：可交互的行号，悬停高亮
- 📋 **智能复制按钮**：悬停显示，点击复制
- 🎨 **语法高亮**：
- 浅色模式：GitHub Light
- 深色模式：One Dark Pro
- 🔤 **等宽字体**：JetBrains Mono, Fira Code, Monaco
- 📏 **行高优化**：1.7 倍行高，更易阅读
#### Mermaid 流程图增强
- 📦 **容器美化**：独立背景 + 圆角边框
- 🎨 **节点样式**：
- 主题色边框（2px）
- 浅色背景填充
- 阴影效果
- ➡️ **连线优化**：
- 主题色连线
- 平滑过渡
- 带箭头指示
- 💡 **悬浮效果**：鼠标悬停时阴影加深
- 🌓 **深色模式适配**：自动切换配色方案
#### 表格增强
- 🎯 **渐变表头**：微妙的渐变背景
- 🔤 **大写标题**：更专业的视觉效果
- 🎨 **主题色强调**：表头使用主题色
- ✨ **悬浮行高亮**：鼠标经过行时高亮
- 📐 **圆角边框**：12px 圆角 + 柔和阴影
- 📱 **横向滚动**：移动端友好
#### 自定义容器
- 💡 **TIP 容器**：蓝色渐变背景
- ⚠️ **WARNING 容器**：橙色渐变背景
- ❌ **DANGER 容器**：红色渐变背景
- ✨ **悬浮动效**：轻微位移 + 阴影加深
- 📏 **统一间距**：24px 外边距，20px 内边距
#### 其他视觉优化
- 🔗 **链接效果**：下划线过渡动画
- 📜 **列表美化**：主题色标记 + 加粗
- 🎬 **淡入动画**：内容加载时淡入效果
- 📜 **渐变滚动条**：主题色渐变
- 🏠 **首页卡片**：悬浮时上浮效果
- ♿ **无障碍优化**：焦点可见 + 高对比度支持
## 🎨 主题配色
### 浅色模式
```css
--vp-c-brand-1: #3451b2 /* 主色 */
--vp-c-brand-2: #3a5ccc /* 强调色 */
--vp-c-brand-3: #5672cd /* 次要色 */
--vp-code-block-bg: #f6f8fa /* 代码背景 */
--vp-mermaid-node-bg: #f0f4ff /* 图表节点 */
```
### 深色模式
```css
--vp-c-brand-1: #6a8dde /* 主色 */
--vp-c-brand-2: #5672cd /* 强调色 */
--vp-c-brand-3: #3451b2 /* 次要色 */
--vp-code-block-bg: #1e1e1e /* 代码背景 */
--vp-mermaid-node-bg: #2a2a3a /* 图表节点 */
```
## 📝 使用示例
### 代码块示例
```typescript
// TypeScript 代码示例
interface Config {
port: number
host: string
theme: 'light' | 'dark'
}
const config: Config = {
port: 5555,
host: '0.0.0.0',
theme: 'light'
}
```
### Mermaid 流程图示例
```mermaid
graph LR
A[开始] --> B{条件判断}
B -->|是| C[执行操作]
B -->|否| D[跳过]
C --> E[结束]
D --> E
```
### 表格示例
| 功能 | 状态 | 说明 |
|------|------|------|
| 远程访问 | ✅ | 绑定 0.0.0.0:5555 |
| 代码高亮 | ✅ | One Dark Pro |
| Mermaid | ✅ | 专业图表样式 |
| 深色模式 | ✅ | 自动切换 |
### 自定义容器示例
::: tip 提示
这是一个提示容器，使用蓝色渐变背景。
:::
::: warning 警告
这是一个警告容器，使用橙色渐变背景。
:::
::: danger 危险
这是一个危险容器，使用红色渐变背景。
:::
## 🚀 启动服务
### 开发模式（推荐）
```bash
# 启动开发服务器（支持热更新）
pnpm dev
# 访问地址
# 本地：http://localhost:5555
# 远程：http://[您的IP]:5555
```
### 生产模式
```bash
# 1. 构建
pnpm build
# 2. 运行生产服务器
pnpm serve
# 访问 http://localhost:5555
```
## 🌐 远程访问设置
### 1. 确认防火墙设置
**macOS:**
```bash
# 允许端口 5555
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add pnpm
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp pnpm
```
**Linux (Ubuntu):**
```bash
sudo ufw allow 5555
```
**Windows:**
- 打开 Windows Defender 防火墙
- 添加入站规则，允许端口 5555
### 2. 获取局域网 IP
```bash
# macOS/Linux
ifconfig | grep "inet " | grep -v 127.0.0.1
# 输出示例
inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255
```
您的访问地址：http://192.168.1.100:5555
### 3. 测试访问
在同一局域网的其他设备上：
1. 打开浏览器
2. 访问 http://[您的IP]:5555
3. 应该能看到文档首页
## 🎨 自定义样式
### 修改主题色
编辑 `docs/.vitepress/theme/custom.css`：
```css
:root {
--vp-c-brand-1: #your-color; /* 修改主题色 */
--vp-c-brand-2: #your-color;
--vp-c-brand-3: #your-color;
}
```
### 修改代码字体
```css
.vp-doc div[class*='language-'] > pre {
font-family: 'Your-Font', monospace;
}
```
### 调整代码块样式
```css
.vp-doc div[class*='language-'] {
border-radius: 12px; /* 圆角大小 */
box-shadow: /* 自定义阴影 */;
}
```
## 📊 性能优化
当前配置已包含：
- ✅ **代码分割**：自动代码分割
- ✅ **懒加载**：图片和组件懒加载
- ✅ **缓存优化**：静态资源长期缓存
- ✅ **压缩**：Gzip/Brotli 压缩
- ✅ **CDN 就绪**：优化的静态资源结构
## 🔧 环境变量
创建 `.env` 文件自定义配置：
```bash
# 服务器端口
PORT=5555
# 监听地址
HOST=0.0.0.0
# 运行环境
NODE_ENV=production
```
## 📱 移动端优化
已自动适配：
- ✅ 响应式布局
- ✅ 触摸优化
- ✅ 字体大小自适应
- ✅ 代码块横向滚动
- ✅ 表格横向滚动
## 🖨️ 打印优化
文档支持打印：
- 自动隐藏导航、侧边栏
- 优化代码块样式
- 保留核心内容
- 优化分页
## 🌍 浏览器支持
- ✅ Chrome/Edge (最新)
- ✅ Firefox (最新)
- ✅ Safari (最新)
- ✅ iOS Safari
- ✅ Chrome Android
## 💡 提示
1. **开发时使用热更新**：修改文件自动刷新
2. **构建前测试**：确保所有功能正常
3. **检查网络**：确保防火墙允许访问
4. **使用 HTTPS**：生产环境建议配置 SSL
## 🆘 故障排查
### 无法远程访问
```bash
# 1. 检查服务是否运行
lsof -i:5555
# 2. 检查防火墙
# macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps
# 3. 测试本地访问
curl http://localhost:5555
# 4. 测试远程访问
curl http://[您的IP]:5555
```
### 样式未生效
```bash
# 清除缓存重启
rm -rf docs/.vitepress/cache
pnpm dev
```
### 图表不显示
- 检查网络连接（Mermaid 需要加载外部资源）
- 查看浏览器控制台错误
- 确认 Mermaid 语法正确
## 📞 获取帮助
- 查看 [README.md](./README.md)
- 查看 [DEPLOYMENT.md](./DEPLOYMENT.md)
- 技术支持：brunogao
DEPLOYMENT.md
+571
View File
@@ -0,0 +1,571 @@
# 部署指南
本文档介绍如何在不同环境中部署 LJWX Docs 文档网站。
## 📋 前置要求
- Node.js 18+
- npm 或 yarn
- Git
## 🚀 快速部署
### 1. 构建项目
```bash
# 克隆仓库（如果还没有）
git clone https://github.com/ljwx/ljwx-docs.git
cd ljwx-docs
# 安装依赖
npm install
# 构建生产版本
npm run docs:build
```
构建完成后，静态文件将生成在 `dist/` 目录。
### 2. 本地测试
```bash
# 方式 1: 使用 VitePress 内置预览
npm run docs:preview
# 方式 2: 使用 Node.js 服务器
npm run docs:serve
```
## 🐳 Docker 部署
### 创建 Dockerfile
在项目根目录创建 `Dockerfile`：
```dockerfile
# 构建阶段
FROM node:18-alpine AS builder
WORKDIR /app
# 复制依赖文件
COPY package*.json ./
RUN npm ci
# 复制源代码
COPY . .
# 构建文档
RUN npm run docs:build
# 生产阶段
FROM node:18-alpine
WORKDIR /app
# 从构建阶段复制文件
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/server.js ./
COPY --from=builder /app/package*.json ./
# 只安装生产依赖
RUN npm ci --only=production
# 暴露端口
EXPOSE 3000
# 设置环境变量
ENV NODE_ENV=production
ENV PORT=3000
ENV HOST=0.0.0.0
# 启动服务
CMD ["node", "server.js"]
```
### 构建和运行
```bash
# 构建镜像
docker build -t ljwx-docs:latest .
# 运行容器
docker run -d \
--name ljwx-docs \
-p 3000:3000 \
--restart unless-stopped \
ljwx-docs:latest
# 查看日志
docker logs -f ljwx-docs
# 停止容器
docker stop ljwx-docs
# 删除容器
docker rm ljwx-docs
```
### Docker Compose
创建 `docker-compose.yml`：
```yaml
version: '3.8'
services:
ljwx-docs:
build: .
container_name: ljwx-docs
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- PORT=3000
- HOST=0.0.0.0
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3000"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
```
运行：
```bash
# 启动
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止
docker-compose down
```
## 🌐 Nginx 部署
### 方式 1: 静态文件托管
适合纯静态部署，性能最佳。
```nginx
server {
listen 80;
server_name docs.ljwx.local;
root /var/www/ljwx-docs/dist;
index index.html;
# 日志
access_log /var/log/nginx/ljwx-docs-access.log;
error_log /var/log/nginx/ljwx-docs-error.log;
# SPA 路由支持
location / {
try_files $uri $uri/ /index.html;
}
# 静态资源缓存
location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public, immutable";
access_log off;
}
# HTML 文件不缓存
location ~* \.html$ {
expires -1;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# Gzip 压缩
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_comp_level 6;
gzip_types
text/plain
text/css
text/xml
text/javascript
application/json
application/javascript
application/xml+rss
application/rss+xml
font/truetype
font/opentype
application/vnd.ms-fontobject
image/svg+xml;
# 安全头
add_header X-Frame-Options "DENY" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
}
```
部署步骤：
```bash
# 1. 构建项目
npm run docs:build
# 2. 复制到服务器
scp -r dist/* user@server:/var/www/ljwx-docs/dist/
# 3. 配置 Nginx
sudo cp nginx.conf /etc/nginx/sites-available/ljwx-docs
sudo ln -s /etc/nginx/sites-available/ljwx-docs /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```
### 方式 2: 反向代理 Node.js
使用 Node.js 服务器 + Nginx 反向代理。
```nginx
upstream ljwx_docs {
server localhost:3000;
}
server {
listen 80;
server_name docs.ljwx.local;
# 日志
access_log /var/log/nginx/ljwx-docs-access.log;
error_log /var/log/nginx/ljwx-docs-error.log;
# 反向代理
location / {
proxy_pass http://ljwx_docs;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
}
# Gzip 压缩
gzip on;
gzip_types text/plain text/css application/json application/javascript;
}
```
## ☸️ Kubernetes 部署
### Deployment 配置
创建 `k8s/deployment.yaml`：
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: ljwx-docs
namespace: ljwx
labels:
app: ljwx-docs
spec:
replicas: 2
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
selector:
matchLabels:
app: ljwx-docs
template:
metadata:
labels:
app: ljwx-docs
spec:
containers:
- name: ljwx-docs
image: ljwx-docs:latest
imagePullPolicy: Always
ports:
- containerPort: 3000
name: http
protocol: TCP
env:
- name: NODE_ENV
value: "production"
- name: PORT
value: "3000"
- name: HOST
value: "0.0.0.0"
resources:
limits:
memory: "256Mi"
cpu: "500m"
requests:
memory: "128Mi"
cpu: "250m"
livenessProbe:
httpGet:
path: /
port: 3000
initialDelaySeconds: 30
periodSeconds: 10
timeoutSeconds: 5
failureThreshold: 3
readinessProbe:
httpGet:
path: /
port: 3000
initialDelaySeconds: 10
periodSeconds: 5
timeoutSeconds: 3
failureThreshold: 3
```
### Service 配置
创建 `k8s/service.yaml`：
```yaml
apiVersion: v1
kind: Service
metadata:
name: ljwx-docs
namespace: ljwx
labels:
app: ljwx-docs
spec:
type: ClusterIP
selector:
app: ljwx-docs
ports:
- port: 80
targetPort: 3000
protocol: TCP
name: http
sessionAffinity: ClientIP
```
### Ingress 配置
创建 `k8s/ingress.yaml`：
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ljwx-docs
namespace: ljwx
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
nginx.ingress.kubernetes.io/ssl-redirect: "false"
nginx.ingress.kubernetes.io/force-ssl-redirect: "false"
spec:
ingressClassName: nginx
rules:
- host: docs.ljwx.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: ljwx-docs
port:
number: 80
```
### 部署
```bash
# 创建命名空间
kubectl create namespace ljwx
# 应用配置
kubectl apply -f k8s/
# 查看状态
kubectl get pods -n ljwx -l app=ljwx-docs
kubectl get svc -n ljwx ljwx-docs
kubectl get ingress -n ljwx ljwx-docs
# 查看日志
kubectl logs -n ljwx -l app=ljwx-docs -f
# 扩容
kubectl scale deployment ljwx-docs -n ljwx --replicas=3
# 更新镜像
kubectl set image deployment/ljwx-docs ljwx-docs=ljwx-docs:v2 -n ljwx
# 回滚
kubectl rollout undo deployment/ljwx-docs -n ljwx
```
## 🔒 HTTPS 配置
### Let's Encrypt (Certbot)
```bash
# 安装 Certbot
sudo apt-get install certbot python3-certbot-nginx
# 获取证书
sudo certbot --nginx -d docs.ljwx.local
# 自动续期
sudo certbot renew --dry-run
```
### 手动证书
```nginx
server {
listen 443 ssl http2;
server_name docs.ljwx.local;
ssl_certificate /etc/nginx/ssl/docs.ljwx.local.crt;
ssl_certificate_key /etc/nginx/ssl/docs.ljwx.local.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;
# 其他配置...
}
server {
listen 80;
server_name docs.ljwx.local;
return 301 https://$server_name$request_uri;
}
```
## 🔧 环境变量
可用的环境变量：
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `NODE_ENV` | 运行环境 | `production` |
| `PORT` | 服务端口 | `3000` |
| `HOST` | 监听地址 | `0.0.0.0` |
## 📊 监控和日志
### PM2 部署（推荐）
```bash
# 安装 PM2
npm install -g pm2
# 启动应用
pm2 start server.js --name ljwx-docs
# 查看状态
pm2 status
# 查看日志
pm2 logs ljwx-docs
# 重启
pm2 restart ljwx-docs
# 开机自启
pm2 startup
pm2 save
```
### Systemd 服务
创建 `/etc/systemd/system/ljwx-docs.service`：
```ini
[Unit]
Description=LJWX Docs Service
After=network.target
[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/ljwx-docs
ExecStart=/usr/bin/node server.js
Restart=on-failure
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=ljwx-docs
Environment=NODE_ENV=production
Environment=PORT=3000
[Install]
WantedBy=multi-user.target
```
管理服务：
```bash
# 启动服务
sudo systemctl start ljwx-docs
# 开机自启
sudo systemctl enable ljwx-docs
# 查看状态
sudo systemctl status ljwx-docs
# 重启
sudo systemctl restart ljwx-docs
# 查看日志
sudo journalctl -u ljwx-docs -f
```
## 🚨 故障排查
### 构建失败
```bash
# 清理缓存
rm -rf node_modules dist .vitepress/cache
npm install
npm run docs:build
```
### 服务启动失败
```bash
# 检查端口占用
lsof -i :3000
# 检查 dist 目录
ls -la dist/
# 查看详细日志
NODE_ENV=production node server.js
```
### Nginx 502 错误
```bash
# 检查 Node.js 服务是否运行
curl http://localhost:3000
# 检查 Nginx 配置
sudo nginx -t
# 查看 Nginx 错误日志
sudo tail -f /var/log/nginx/error.log
```
## 📞 获取帮助
如遇到部署问题：
- 查看项目 [Issues](https://github.com/ljwx/ljwx-docs/issues)
- 联系技术支持：brunogao
GETTING-STARTED.md
+174
View File
@@ -0,0 +1,174 @@
# 快速上手指南
欢迎使用 LJWX Docs！本指南将帮助您在 5 分钟内启动文档网站。
## 🎯 第一步：安装依赖
```bash
# 确保您已安装 Node.js 18+
node --version
# 安装项目依赖
npm install
```
## 🚀 第二步：启动开发服务器
```bash
npm run docs:dev
```
访问 http://localhost:5173，您将看到文档网站。
## 📝 第三步：配置 Giscus 评论系统（可选）
如果您想启用评论功能，请按以下步骤操作：
### 3.1 准备 GitHub 仓库
1. 创建一个公开的 GitHub 仓库（或使用现有仓库）
2. 在仓库设置中启用 Discussions 功能
3. 访问 https://giscus.app/zh-CN
### 3.2 获取配置信息
在 Giscus 网站上：
1. 输入您的仓库名（格式：`username/repo`）
2. 选择页面与 discussions 映射关系（推荐：pathname）
3. 选择 Discussion 分类（推荐：General）
4. 复制生成的配置信息
### 3.3 更新配置
编辑 `docs/.vitepress/theme/components/GiscusComment.vue`：
```typescript
// 第 30-33 行
const repo = computed(() => 'your-username/your-repo') // 替换为您的仓库
const repoId = computed(() => 'R_kgDOxxxxxx') // 替换为您的仓库 ID
const category = computed(() => 'General') // 讨论分类
const categoryId = computed(() => 'DIC_kwDOxxxxxx') // 替换为您的分类 ID
```
## 🎨 第四步：自定义配置（可选）
### 修改网站信息
编辑 `docs/.vitepress/config.ts`：
```typescript
export default defineConfig({
title: "您的文档标题",
description: "您的文档描述",
// ...
})
```
### 修改主题颜色
编辑 `docs/.vitepress/theme/custom.css`：
```css
:root {
--vp-c-brand-1: #3451b2; /* 修改为您喜欢的颜色 */
--vp-c-brand-2: #3a5ccc;
--vp-c-brand-3: #5672cd;
}
```
### 更新 Logo
替换 `docs/public/logo.svg` 为您自己的 Logo。
## 🏗️ 第五步：构建生产版本
```bash
# 构建
npm run docs:build
# 预览构建结果
npm run docs:preview
# 或使用 Node.js 服务器
npm run docs:serve
```
## 📦 常用命令
| 命令 | 说明 |
|------|------|
| `npm run docs:dev` | 启动开发服务器 |
| `npm run docs:build` | 构建生产版本 |
| `npm run docs:preview` | 预览构建结果 |
| `npm run docs:serve` | 使用 Node.js 服务器运行 |
## 📚 下一步
- 阅读 [README.md](./README.md) 了解项目结构
- 查看 [DEPLOYMENT.md](./DEPLOYMENT.md) 学习部署方法
- 浏览文档网站了解更多功能
## 🎓 快速学习
### 添加新文档
1. 在 `docs/` 目录创建 `.md` 文件
2. 在 `docs/.vitepress/config.ts` 更新侧边栏
3. 保存后自动刷新
### 使用 Frontmatter
在文档顶部添加元数据：
```yaml
---
title: 文档标题
description: 文档描述
comment: false # 禁用评论
---
```
### 添加多语言版本
1. 在 `docs/en/` 创建对应的英文文档
2. 文件路径保持一致
3. 更新 `config.ts` 中的英文侧边栏
## ❓ 常见问题
### 端口被占用
```bash
# 修改端口
npm run docs:dev -- --port 5174
```
### 构建失败
```bash
# 清理缓存重试
rm -rf node_modules .vitepress/cache dist
npm install
npm run docs:build
```
### 评论系统不显示
1. 检查 GitHub 仓库是否公开
2. 确认已启用 Discussions
3. 验证配置信息是否正确
## 💡 提示
- 开发时保存文件会自动热重载
- 使用搜索功能快速找到内容
- 主题自动跟随系统（可手动切换）
- 支持中英文切换
## 📞 获取帮助
- 查看完整文档：启动网站后访问首页
- 技术支持：brunogao
- 问题反馈：[GitHub Issues](https://github.com/ljwx/ljwx-docs/issues)
祝您使用愉快！🎉
PROJECT-SUMMARY.md
+265
View File
@@ -0,0 +1,265 @@
# 项目配置总结
## ✅ 已完成的配置
### 1. 基础框架 ✨
- ✅ VitePress 1.0.1 框架
- ✅ TypeScript 配置
- ✅ 项目依赖管理
### 2. 核心功能 🎯
- ✅ **多语言支持** - 中文/英文双语
- ✅ **本地搜索** - 全文搜索功能
- ✅ **深色模式** - 自动跟随系统主题
- ✅ **评论系统** - Giscus 集成（需配置）
- ✅ **响应式设计** - 完美适配移动端
### 3. 文档内容 📚
- ✅ 中文首页（带功能展示）
- ✅ 英文首页
- ✅ 快速参考文档
- ✅ 架构设计文档
- ✅ 使用指南
- ✅ Dify 同步指南
- ✅ 指南索引页
### 4. 主题定制 🎨
- ✅ 自定义颜色方案
- ✅ 自定义布局（集成评论）
- ✅ 自定义样式（优化阅读体验）
- ✅ Logo 设计
### 5. 部署方案 🚀
- ✅ Node.js 服务器
- ✅ Docker 配置文档
- ✅ Nginx 配置文档
- ✅ Kubernetes 配置文档
- ✅ HTTPS 配置指南
### 6. 文档和指南 📖
- ✅ README.md
- ✅ GETTING-STARTED.md
- ✅ DEPLOYMENT.md
- ✅ .gitignore
## 📁 项目结构
```
ljwx-docs/
├── docs/ # 文档源文件
│ ├── .vitepress/ # VitePress 配置
│ │ ├── config.ts # 主配置（多语言、搜索、主题）
│ │ └── theme/ # 自定义主题
│ │ ├── components/
│ │ │ └── GiscusComment.vue # 评论组件
│ │ ├── custom.css # 自定义样式
│ │ ├── index.ts # 主题入口
│ │ └── Layout.vue # 自定义布局
│ ├── public/
│ │ └── logo.svg # 网站 Logo
│ ├── en/ # 英文文档
│ │ ├── index.md # 英文首页
│ │ ├── guide/
│ │ │ └── index.md
│ │ ├── QUICK-REFERENCE.md
│ │ ├── knowledge-asset-automation-design.md
│ │ ├── knowledge-asset-usage-guide.md
│ │ └── dify-knowledge-sync-guide.md
│ ├── guide/
│ │ └── index.md # 指南索引
│ ├── index.md # 中文首页
│ ├── QUICK-REFERENCE.md # 快速参考
│ ├── knowledge-asset-automation-design.md
│ ├── knowledge-asset-usage-guide.md
│ └── dify-knowledge-sync-guide.md
├── server.js # Node.js 生产服务器
├── package.json # 项目配置
├── .gitignore # Git 忽略文件
├── README.md # 项目说明
├── GETTING-STARTED.md # 快速上手
├── DEPLOYMENT.md # 部署指南
└── PROJECT-SUMMARY.md # 本文件
```
## 🚀 快速开始
### 1. 安装依赖
```bash
npm install
```
### 2. 启动开发服务器
```bash
npm run docs:dev
```
访问 http://localhost:5173
### 3. 配置 Giscus（可选但推荐）
编辑 `docs/.vitepress/theme/components/GiscusComment.vue`：
```typescript
const repo = computed(() => 'your-username/your-repo')
const repoId = computed(() => 'R_kgDOxxxxxx')
const category = computed(() => 'General')
const categoryId = computed(() => 'DIC_kwDOxxxxxx')
```
获取配置：https://giscus.app/zh-CN
### 4. 构建和部署
```bash
# 构建
npm run docs:build
# 使用 Node.js 服务器
npm run docs:serve
```
## 🎨 自定义配置
### 修改网站信息
`docs/.vitepress/config.ts`:
```typescript
title: "您的标题"
description: "您的描述"
```
### 修改主题颜色
`docs/.vitepress/theme/custom.css`:
```css
:root {
--vp-c-brand-1: #3451b2; /* 主题色 */
}
```
### 更新 Logo
替换 `docs/public/logo.svg`
### 修改社交链接
`docs/.vitepress/config.ts`:
```typescript
socialLinks: [
{ icon: 'github', link: 'https://github.com/your-org' }
]
```
## 📝 添加新文档
1. 在 `docs/` 创建 `.md` 文件
2. 在 `docs/.vitepress/config.ts` 更新侧边栏
3. 如需英文版，在 `docs/en/` 创建对应文件
## 🌐 多语言管理
- 中文文档：`docs/`
- 英文文档：`docs/en/`
- 配置文件：`docs/.vitepress/config.ts` 的 `locales` 部分
添加新语言：
1. 在 `config.ts` 添加语言配置
2. 创建对应目录（如 `docs/ja/`）
3. 翻译内容
## 💬 评论系统配置
### 前置要求
- GitHub 公开仓库
- 启用 Discussions
### 配置步骤
1. 访问 https://giscus.app/zh-CN
2. 输入仓库信息
3. 获取配置代码
4. 更新 `GiscusComment.vue`
### 禁用评论
在文档 frontmatter 添加：
```yaml
---
comment: false
---
```
## 🚀 部署选项
### 1. Node.js 服务器（简单）
```bash
npm run docs:build
npm run docs:serve
```
### 2. Docker（推荐）
参考 `DEPLOYMENT.md` 的 Docker 部分
### 3. Nginx 静态托管（性能最佳）
参考 `DEPLOYMENT.md` 的 Nginx 部分
### 4. Kubernetes（企业级）
参考 `DEPLOYMENT.md` 的 K8s 部分
## 📊 特性对比
| 特性 | 状态 | 说明 |
|------|------|------|
| 搜索功能 | ✅ | 本地搜索，支持全文检索 |
| 深色模式 | ✅ | 自动跟随系统，可手动切换 |
| 多语言 | ✅ | 中英文，可扩展 |
| 评论系统 | ⚙️ | 需配置 Giscus |
| 响应式 | ✅ | 完美适配移动端 |
| SEO 优化 | ✅ | 清理 URL、Meta 标签 |
| 代码高亮 | ✅ | 支持行号和主题切换 |
| Markdown 扩展 | ✅ | 容器、表格、代码组等 |
## 🔧 可选增强
### Algolia 搜索
替换本地搜索为 Algolia（需注册）
### PWA 支持
添加 Service Worker 支持离线访问
### Google Analytics
添加访问统计
### 图片优化
使用 CDN 或图片压缩
## 📞 获取帮助
- **快速上手**：查看 `GETTING-STARTED.md`
- **项目说明**：查看 `README.md`
- **部署指南**：查看 `DEPLOYMENT.md`
- **技术支持**：brunogao
- **问题反馈**：GitHub Issues
## ✨ 下一步建议
1. ✅ 安装依赖并启动开发服务器
2. ⏳ 配置 Giscus 评论系统
3. ⏳ 自定义网站信息和主题
4. ⏳ 添加/更新文档内容
5. ⏳ 构建并部署到生产环境
6. ⏳ 配置域名和 HTTPS
7. ⏳ 监控和优化
## 🎉 完成
所有核心功能已配置完成，可以开始使用了！
如有任何问题，请参考相关文档或联系技术支持。
---
**项目版本**: 1.0.0
**配置日期**: 2025-01-23
**技术栈**: VitePress 1.0 + Vue 3 + TypeScript
**维护者**: brunogao
README.md
+399
View File
@@ -0,0 +1,399 @@
# LJWX Docs - 知识资产化系统文档
基于 VitePress 构建的知识资产化系统文档网站，支持多语言、搜索、深色模式、评论系统和专业级视觉效果。
## ✨ 核心特性
### 📚 知识管理
- **知识资产化** - 元数据驱动的文档管理系统
- **自动化发布** - 集成 CI/CD，自动同步到知识库
- **Dify 集成** - 支持同步到 Dify 知识库系统
- **版本追踪** - Git commit hash 关联，变更可追溯
### 🎨 专业视觉
- **代码块增强** - 圆角阴影、悬浮效果、智能复制按钮、JetBrains Mono 字体
- **流程图优化** - Mermaid 专业样式、主题色节点、平滑连线、阴影效果
- **表格美化** - 渐变表头、行悬浮高亮、圆角边框、主题色强调
- **容器增强** - TIP/WARNING/DANGER 渐变背景、悬浮动效
- **动画效果** - 淡入动画、过渡效果、渐变滚动条
### 🌐 访问与交互
- **远程访问** - 支持局域网内任何设备访问（0.0.0.0:5555）
- **本地搜索** - 内置全文搜索功能（Cmd+K 快捷键）
- **深色模式** - 自动适配系统主题，所有元素完美适配
- **评论系统** - 基于 Giscus 的 GitHub Discussions
- **多语言** - 支持中英文双语，可扩展
- **响应式设计** - 完美适配桌面和移动端
## 🚀 快速开始
### 安装依赖
```bash
# 使用 pnpm（推荐）
pnpm install
# 或使用 npm
npm install
```
### 本地开发
```bash
# 简短命令
pnpm dev
# 或使用完整命令
pnpm docs:dev
```
**访问地址：**
- 本地：http://localhost:5555
- 远程：http://[您的IP]:5555（局域网内其他设备）
**获取您的 IP 地址：**
```bash
# macOS/Linux
ifconfig | grep "inet " | grep -v 127.0.0.1
# Windows
ipconfig
```
### 构建生产版本
```bash
# 构建
pnpm build
# 预览构建结果
pnpm preview
```
### 生产环境部署
```bash
# 构建静态文件
pnpm build
# 使用 Node.js 服务器运行（需先构建）
pnpm serve
```
## 🌟 视觉特性展示
### 代码块效果
- ✨ **圆角阴影设计** - 12px 圆角 + 柔和阴影
- 🎯 **悬浮交互** - 鼠标悬停时轻微上浮效果
- 📋 **智能复制** - 悬停显示复制按钮，一键复制代码
- 🔢 **行号优化** - 可交互行号，悬停高亮
- 🎨 **语法高亮** - 浅色 GitHub Light / 深色 One Dark Pro
- 🔤 **专业字体** - JetBrains Mono, Fira Code, Monaco
### Mermaid 流程图
- 📦 **独立容器** - 白色背景 + 圆角边框
- 🎨 **主题色节点** - 品牌色边框 + 阴影效果
- ➡️ **平滑连线** - 主题色连线 + 箭头指示
- 💡 **悬浮增强** - 鼠标悬停时阴影加深
- 🌓 **深色适配** - 完美的深色模式配色
### 表格样式
- 🎯 **渐变表头** - 现代渐变背景
- 🔤 **大写标题** - 专业的视觉效果
- 🎨 **主题色强调** - 表头使用品牌色
- ✨ **行悬浮** - 鼠标经过时行高亮
- 📐 **圆角边框** - 12px 圆角 + 柔和阴影
## 📖 文档说明
- **[GETTING-STARTED.md](./GETTING-STARTED.md)** - 5分钟快速上手指南
- **[CONFIGURATION.md](./CONFIGURATION.md)** - 远程访问和视觉优化配置详解
- **[DEPLOYMENT.md](./DEPLOYMENT.md)** - Docker/Nginx/K8s 部署方案
- **[PROJECT-SUMMARY.md](./PROJECT-SUMMARY.md)** - 项目完整总结
## 📁 项目结构
```
ljwx-docs/
├── docs/ # 文档源文件
│ ├── .vitepress/ # VitePress 配置
│ │ ├── config.ts # 主配置文件
│ │ └── theme/ # 自定义主题
│ │ ├── components/ # Vue 组件
│ │ ├── custom.css # 自定义样式
│ │ ├── index.ts # 主题入口
│ │ └── Layout.vue # 自定义布局
│ ├── en/ # 英文文档
│ ├── guide/ # 指南目录
│ ├── index.md # 中文首页
│ ├── QUICK-REFERENCE.md # 快速参考
│ ├── knowledge-asset-automation-design.md
│ ├── knowledge-asset-usage-guide.md
│ └── dify-knowledge-sync-guide.md
├── server.js # Node.js 生产服务器
├── package.json # 项目配置
├── .gitignore # Git 忽略文件
└── README.md # 本文件
```
## 🔧 配置说明
### VitePress 配置
主配置文件位于 `docs/.vitepress/config.ts`，包括：
- 多语言配置
- 导航和侧边栏
- 搜索配置
- 主题定制
### 评论系统配置
编辑 `docs/.vitepress/theme/components/GiscusComment.vue` 中的配置：
```typescript
const repo = computed(() => 'your-username/your-repo')
const repoId = computed(() => 'R_kgDOxxxxxx')
const category = computed(() => 'General')
const categoryId = computed(() => 'DIC_kwDOxxxxxx')
```
获取这些值：
1. 访问 https://giscus.app/zh-CN
2. 输入你的 GitHub 仓库
3. 按照指引获取配置值
### 禁用评论
在文档的 frontmatter 中添加：
```yaml
---
comment: false
---
```
## 🌐 多语言支持
当前支持：
- 🇨🇳 简体中文 (默认)
- 🇺🇸 English
添加新语言：
1. 在 `docs/.vitepress/config.ts` 中添加语言配置
2. 创建对应的语言目录（如 `docs/ja/`）
3. 翻译文档内容
## 📦 部署
### Docker 部署
创建 `Dockerfile`：
```dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run docs:build
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/server.js ./
COPY --from=builder /app/package*.json ./
RUN npm ci --only=production
EXPOSE 3000
CMD ["node", "server.js"]
```
构建和运行：
```bash
docker build -t ljwx-docs .
docker run -p 3000:3000 ljwx-docs
```
### Nginx 部署
构建静态文件后，使用 Nginx 托管：
```nginx
server {
listen 80;
server_name docs.ljwx.local;
root /var/www/ljwx-docs/dist;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
# 静态资源缓存
location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# HTML 文件不缓存
location ~* \.html$ {
add_header Cache-Control "no-cache, must-revalidate";
}
# Gzip 压缩
gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}
```
### Kubernetes 部署
创建 `k8s-deployment.yaml`：
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: ljwx-docs
spec:
replicas: 2
selector:
matchLabels:
app: ljwx-docs
template:
metadata:
labels:
app: ljwx-docs
spec:
containers:
- name: ljwx-docs
image: ljwx-docs:latest
ports:
- containerPort: 3000
resources:
limits:
memory: "256Mi"
cpu: "500m"
requests:
memory: "128Mi"
cpu: "250m"
---
apiVersion: v1
kind: Service
metadata:
name: ljwx-docs
spec:
selector:
app: ljwx-docs
ports:
- port: 80
targetPort: 3000
type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ljwx-docs
spec:
rules:
- host: docs.ljwx.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: ljwx-docs
port:
number: 80
```
部署：
```bash
kubectl apply -f k8s-deployment.yaml
```
## 🛠️ 开发指南
### 添加新文档
1. 在 `docs/` 目录下创建 `.md` 文件
2. 添加 frontmatter（可选）
3. 在 `docs/.vitepress/config.ts` 中更新导航/侧边栏
4. 如需英文版，在 `docs/en/` 创建对应文件
### 自定义主题
编辑 `docs/.vitepress/theme/custom.css` 修改样式：
```css
:root {
--vp-c-brand-1: #3451b2; /* 主题色 */
--vp-c-brand-2: #3a5ccc;
--vp-c-brand-3: #5672cd;
}
```
### 添加 Vue 组件
1. 在 `docs/.vitepress/theme/components/` 创建组件
2. 在 `docs/.vitepress/theme/index.ts` 注册
3. 在 markdown 中使用
## 🔗 仓库信息
- **Git 仓库**: http://192.168.1.83:33000/gao/ljwx-docs.git
- **在线访问**: http://192.168.1.83:5555（开发服务器运行时）
## 📄 许可证
MIT License
## 👥 贡献
欢迎提交 Issue 和 Pull Request！
### 克隆仓库
```bash
git clone http://192.168.1.83:33000/gao/ljwx-docs.git
cd ljwx-docs
pnpm install
pnpm dev
```
## 📞 支持与反馈
- **技术支持**: brunogao
- **文档仓库**: http://192.168.1.83:33000/gao/ljwx-docs
- **问题反馈**: 提交 Issue 到仓库
## 🎯 下一步
1. ✅ 配置 Giscus 评论系统（可选）
2. ✅ 自定义主题颜色和样式
3. ✅ 添加/更新文档内容
4. ✅ 配置 CI/CD 自动部署
5. ✅ 配置域名和 HTTPS
## 🌟 项目亮点
- 🚀 **即开即用** - 5分钟快速启动
- 🎨 **专业视觉** - 媲美顶级文档站点
- 🌐 **远程访问** - 局域网内任意设备访问
- 📱 **移动优化** - 完美的响应式设计
- 🌓 **深色模式** - 所有元素完美适配
- ⚡ **性能优异** - 流畅的动画和交互
- 📚 **丰富文档** - 详细的配置和部署指南
---
**版本**: 1.0.0
**更新日期**: 2025-01-23
**技术栈**: VitePress 1.0 + Vue 3 + TypeScript
**维护者**: brunogao
docs/.vitepress/config.ts
+198
View File
@@ -0,0 +1,198 @@
import { defineConfig } from 'vitepress'
// https://vitepress.dev/reference/site-config
export default defineConfig({
title: "LJWX Docs",
description: "知识资产化系统文档",
// 多语言配置
locales: {
root: {
label: '简体中文',
lang: 'zh-CN',
themeConfig: {
nav: [
{ text: '首页', link: '/' },
{ text: '快速开始', link: '/QUICK-REFERENCE' },
{ text: '指南', link: '/guide/' }
],
sidebar: {
'/guide/': [
{
text: '指南',
items: [
{ text: '架构设计', link: '/knowledge-asset-automation-design' },
{ text: '使用指南', link: '/knowledge-asset-usage-guide' },
{ text: 'Dify 同步指南', link: '/dify-knowledge-sync-guide' },
{ text: '快速参考', link: '/QUICK-REFERENCE' }
]
}
]
},
footer: {
message: '基于 VitePress 构建',
copyright: 'Copyright © 2025 LJWX'
},
docFooter: {
prev: '上一页',
next: '下一页'
},
outline: {
label: '页面导航',
level: [2, 3]
},
lastUpdated: {
text: '最后更新于',
formatOptions: {
dateStyle: 'short',
timeStyle: 'medium'
}
},
returnToTopLabel: '回到顶部',
sidebarMenuLabel: '菜单',
darkModeSwitchLabel: '主题',
lightModeSwitchTitle: '切换到浅色模式',
darkModeSwitchTitle: '切换到深色模式'
}
},
en: {
label: 'English',
lang: 'en-US',
link: '/en/',
themeConfig: {
nav: [
{ text: 'Home', link: '/en/' },
{ text: 'Quick Start', link: '/en/QUICK-REFERENCE' },
{ text: 'Guide', link: '/en/guide/' }
],
sidebar: {
'/en/guide/': [
{
text: 'Guide',
items: [
{ text: 'Architecture Design', link: '/en/knowledge-asset-automation-design' },
{ text: 'Usage Guide', link: '/en/knowledge-asset-usage-guide' },
{ text: 'Dify Sync Guide', link: '/en/dify-knowledge-sync-guide' },
{ text: 'Quick Reference', link: '/en/QUICK-REFERENCE' }
]
}
]
},
footer: {
message: 'Built with VitePress',
copyright: 'Copyright © 2025 LJWX'
},
docFooter: {
prev: 'Previous',
next: 'Next'
},
outline: {
label: 'On this page'
},
lastUpdated: {
text: 'Last updated'
}
}
}
},
// 主题配置
themeConfig: {
logo: '/logo.svg',
// 社交链接
socialLinks: [
{ icon: 'github', link: 'https://github.com/ljwx' }
],
// 搜索配置 - 使用本地搜索
search: {
provider: 'local',
options: {
locales: {
root: {
translations: {
button: {
buttonText: '搜索文档',
buttonAriaLabel: '搜索文档'
},
modal: {
noResultsText: '无法找到相关结果',
resetButtonTitle: '清除查询条件',
footer: {
selectText: '选择',
navigateText: '切换',
closeText: '关闭'
}
}
}
},
en: {
translations: {
button: {
buttonText: 'Search',
buttonAriaLabel: 'Search'
},
modal: {
noResultsText: 'No results found',
resetButtonTitle: 'Reset search',
footer: {
selectText: 'to select',
navigateText: 'to navigate',
closeText: 'to close'
}
}
}
}
}
}
}
},
// 最后更新时间
lastUpdated: true,
// 清理 URL
cleanUrls: true,
// Markdown 配置
markdown: {
lineNumbers: true,
theme: {
light: 'github-light',
dark: 'one-dark-pro'
},
// 代码块配置
codeTransformers: [
// 添加代码组支持
]
},
// Mermaid 图表支持
mermaid: {
// Mermaid 配置
},
// 启用 MermaidJS
vite: {
optimizeDeps: {
include: ['mermaid']
}
},
// 构建配置
build: {
outDir: '../dist'
}
})
docs/.vitepress/theme/Layout.vue
+21
View File
@@ -0,0 +1,21 @@
<template>
<DefaultTheme.Layout>
<template #doc-after>
<GiscusComment v-if="enableComment" />
</template>
</DefaultTheme.Layout>
</template>
<script setup lang="ts">
import { computed } from 'vue'
import { useData } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import GiscusComment from './components/GiscusComment.vue'
const { frontmatter } = useData()
// 默认启用评论，可通过 frontmatter 的 comment: false 禁用
const enableComment = computed(() => {
return frontmatter.value.comment !== false
})
</script>
docs/.vitepress/theme/components/GiscusComment.vue
+79
View File
@@ -0,0 +1,79 @@
<template>
<div class="giscus-container">
<component :is="'script'"
src="https://giscus.app/client.js"
:data-repo="repo"
:data-repo-id="repoId"
:data-category="category"
:data-category-id="categoryId"
data-mapping="pathname"
data-strict="0"
data-reactions-enabled="1"
data-emit-metadata="0"
data-input-position="top"
:data-theme="theme"
:data-lang="lang"
data-loading="lazy"
crossorigin="anonymous"
async>
</component>
</div>
</template>
<script setup lang="ts">
import { computed, onMounted, watch } from 'vue'
import { useData } from 'vitepress'
const { isDark, lang: docLang } = useData()
// Giscus 配置
// 请替换为您自己的 GitHub 仓库信息
const repo = computed(() => 'ljwx/ljwx-docs') // 替换为您的仓库
const repoId = computed(() => 'R_kgDOxxxxxx') // 替换为您的仓库 ID
const category = computed(() => 'General') // 讨论分类
const categoryId = computed(() => 'DIC_kwDOxxxxxx') // 替换为您的分类 ID
// 主题跟随 VitePress
const theme = computed(() => isDark.value ? 'dark' : 'light')
// 语言跟随文档
const lang = computed(() => docLang.value === 'zh-CN' ? 'zh-CN' : 'en')
// 监听主题变化，动态更新 Giscus
watch([isDark, docLang], () => {
const iframe = document.querySelector<HTMLIFrameElement>('iframe.giscus-frame')
if (!iframe) return
iframe.contentWindow?.postMessage(
{
giscus: {
setConfig: {
theme: theme.value,
lang: lang.value
}
}
},
'https://giscus.app'
)
})
onMounted(() => {
// 初始化时的处理
console.log('Giscus comment system loaded')
})
</script>
<style scoped>
.giscus-container {
margin-top: 3rem;
padding-top: 2rem;
border-top: 1px solid var(--vp-c-divider);
}
@media (max-width: 768px) {
.giscus-container {
margin-top: 2rem;
padding-top: 1.5rem;
}
}
</style>
docs/.vitepress/theme/custom.css
+516
View File
@@ -0,0 +1,516 @@
/**
* LJWX Docs - 专业文档主题样式
* 优化代码、流程图、架构图等的显示效果
*/
/* ============================================
主题色彩系统
============================================ */
:root {
/* 主品牌色 - 现代蓝色渐变 */
--vp-c-brand-1: #3451b2;
--vp-c-brand-2: #3a5ccc;
--vp-c-brand-3: #5672cd;
--vp-c-brand-soft: rgba(52, 81, 178, 0.14);
/* 辅助色彩 */
--vp-c-tip-1: #3451b2;
--vp-c-tip-2: #3a5ccc;
--vp-c-tip-3: #5672cd;
/* 代码块颜色 */
--vp-code-block-bg: #f6f8fa;
--vp-code-bg: #f6f8fa;
--vp-code-tab-divider: rgba(125, 125, 125, 0.2);
--vp-code-copy-code-bg: rgba(125, 125, 125, 0.1);
/* 代码高亮增强 */
--vp-code-line-highlight-color: rgba(52, 81, 178, 0.08);
--vp-code-line-number-color: rgba(125, 125, 125, 0.4);
/* 图表和图形 */
--vp-mermaid-bg: #ffffff;
--vp-mermaid-node-bg: #f0f4ff;
--vp-mermaid-edge-color: #3451b2;
}
.dark {
/* 深色模式品牌色 */
--vp-c-brand-1: #6a8dde;
--vp-c-brand-2: #5672cd;
--vp-c-brand-3: #3451b2;
--vp-c-brand-soft: rgba(106, 141, 222, 0.16);
/* 深色模式辅助色 */
--vp-c-tip-1: #6a8dde;
--vp-c-tip-2: #5672cd;
--vp-c-tip-3: #3451b2;
/* 深色模式代码块 */
--vp-code-block-bg: #1e1e1e;
--vp-code-bg: #1e1e1e;
--vp-code-line-highlight-color: rgba(106, 141, 222, 0.1);
/* 深色模式图表 */
--vp-mermaid-bg: #1a1a1a;
--vp-mermaid-node-bg: #2a2a3a;
--vp-mermaid-edge-color: #6a8dde;
}
/* ============================================
代码块专业样式
============================================ */
/* 代码块容器 */
.vp-doc div[class*='language-'] {
position: relative;
margin: 24px 0;
border-radius: 12px;
background-color: var(--vp-code-block-bg);
overflow: hidden;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04),
0 1px 2px rgba(0, 0, 0, 0.06);
transition: box-shadow 0.3s ease, transform 0.2s ease;
}
.vp-doc div[class*='language-']:hover {
box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08),
0 2px 4px rgba(0, 0, 0, 0.1);
transform: translateY(-1px);
}
/* 深色模式代码块阴影 */
.dark .vp-doc div[class*='language-'] {
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3),
0 1px 2px rgba(0, 0, 0, 0.4);
}
.dark .vp-doc div[class*='language-']:hover {
box-shadow: 0 4px 16px rgba(0, 0, 0, 0.4),
0 2px 4px rgba(0, 0, 0, 0.5);
}
/* 语言标签美化 */
.vp-doc div[class*='language-']::before {
position: absolute;
top: 12px;
right: 16px;
z-index: 2;
font-size: 12px;
font-weight: 600;
color: var(--vp-c-text-2);
text-transform: uppercase;
letter-spacing: 0.5px;
opacity: 0.6;
}
/* 代码内容区域 */
.vp-doc div[class*='language-'] > pre {
padding: 20px 24px;
line-height: 1.7;
font-size: 14px;
font-family: 'JetBrains Mono', 'Fira Code', 'Monaco', 'Menlo', monospace;
}
/* 行号样式 */
.vp-doc div[class*='language-'].line-numbers-mode .line-numbers {
padding: 20px 0;
line-height: 1.7;
font-size: 14px;
color: var(--vp-code-line-number-color);
user-select: none;
}
.vp-doc div[class*='language-'].line-numbers-mode .line-numbers .line-number {
transition: color 0.2s;
}
.vp-doc div[class*='language-'].line-numbers-mode .line-numbers .line-number:hover {
color: var(--vp-c-brand-1);
}
/* 复制按钮美化 */
.vp-doc div[class*='language-'] button.copy {
position: absolute;
top: 12px;
right: 12px;
z-index: 3;
width: 36px;
height: 36px;
border-radius: 8px;
background-color: var(--vp-code-copy-code-bg);
transition: all 0.2s ease;
opacity: 0;
}
.vp-doc div[class*='language-']:hover button.copy {
opacity: 1;
}
.vp-doc div[class*='language-'] button.copy:hover {
background-color: var(--vp-c-brand-1);
transform: scale(1.05);
}
.vp-doc div[class*='language-'] button.copy:hover .vpi-copy {
color: #ffffff;
}
/* 代码块高亮行 */
.vp-doc div[class*='language-'] .highlighted {
background-color: var(--vp-code-line-highlight-color);
display: block;
margin: 0 -24px;
padding: 0 24px;
border-left: 3px solid var(--vp-c-brand-1);
}
/* ============================================
Mermaid 流程图专业样式
============================================ */
/* Mermaid 容器 */
.vp-doc .vp-mermaid {
margin: 32px 0;
padding: 24px;
background: var(--vp-mermaid-bg);
border-radius: 12px;
border: 1px solid var(--vp-c-divider);
box-shadow: 0 2px 12px rgba(0, 0, 0, 0.04);
overflow-x: auto;
transition: box-shadow 0.3s ease;
}
.vp-doc .vp-mermaid:hover {
box-shadow: 0 4px 20px rgba(0, 0, 0, 0.08);
}
.dark .vp-doc .vp-mermaid {
box-shadow: 0 2px 12px rgba(0, 0, 0, 0.3);
}
.dark .vp-doc .vp-mermaid:hover {
box-shadow: 0 4px 20px rgba(0, 0, 0, 0.4);
}
/* Mermaid 图形元素样式 */
.vp-doc .mermaid svg {
max-width: 100%;
height: auto;
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}
/* Mermaid 节点样式 */
.vp-doc .mermaid .node rect,
.vp-doc .mermaid .node circle,
.vp-doc .mermaid .node ellipse,
.vp-doc .mermaid .node polygon {
fill: var(--vp-mermaid-node-bg) !important;
stroke: var(--vp-c-brand-1) !important;
stroke-width: 2px !important;
filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1));
}
/* Mermaid 边线样式 */
.vp-doc .mermaid .edgePath .path {
stroke: var(--vp-mermaid-edge-color) !important;
stroke-width: 2px !important;
}
/* Mermaid 箭头样式 */
.vp-doc .mermaid .arrowheadPath {
fill: var(--vp-mermaid-edge-color) !important;
}
/* Mermaid 文本样式 */
.vp-doc .mermaid .nodeLabel,
.vp-doc .mermaid .edgeLabel {
font-weight: 500;
color: var(--vp-c-text-1) !important;
}
/* ============================================
表格专业样式
============================================ */
.vp-doc table {
display: block;
width: 100%;
overflow-x: auto;
margin: 24px 0;
border-radius: 12px;
border: 1px solid var(--vp-c-divider);
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04);
}
.dark .vp-doc table {
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
}
.vp-doc table thead {
background: linear-gradient(180deg,
var(--vp-c-bg-soft) 0%,
var(--vp-c-bg) 100%);
}
.vp-doc table th {
font-weight: 600;
font-size: 14px;
text-transform: uppercase;
letter-spacing: 0.5px;
color: var(--vp-c-brand-1);
padding: 16px 20px;
border-bottom: 2px solid var(--vp-c-brand-1);
}
.vp-doc table td {
padding: 14px 20px;
border-bottom: 1px solid var(--vp-c-divider);
}
.vp-doc table tbody tr {
transition: background-color 0.2s ease;
}
.vp-doc table tbody tr:hover {
background-color: var(--vp-c-bg-soft);
}
.vp-doc table tbody tr:last-child td {
border-bottom: none;
}
/* ============================================
自定义容器增强
============================================ */
.vp-doc .custom-block {
margin: 24px 0;
padding: 20px 24px;
border-radius: 12px;
border-left: 4px solid;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04);
transition: box-shadow 0.3s ease, transform 0.2s ease;
}
.vp-doc .custom-block:hover {
box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);
transform: translateX(2px);
}
.dark .vp-doc .custom-block {
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
}
.dark .vp-doc .custom-block:hover {
box-shadow: 0 4px 16px rgba(0, 0, 0, 0.4);
}
.vp-doc .custom-block.tip {
border-left-color: var(--vp-c-brand-1);
background: linear-gradient(135deg,
rgba(52, 81, 178, 0.05) 0%,
rgba(52, 81, 178, 0.02) 100%);
}
.vp-doc .custom-block.warning {
border-left-color: #f59e0b;
background: linear-gradient(135deg,
rgba(245, 158, 11, 0.05) 0%,
rgba(245, 158, 11, 0.02) 100%);
}
.vp-doc .custom-block.danger {
border-left-color: #ef4444;
background: linear-gradient(135deg,
rgba(239, 68, 68, 0.05) 0%,
rgba(239, 68, 68, 0.02) 100%);
}
/* ============================================
列表样式增强
============================================ */
.vp-doc ul,
.vp-doc ol {
padding-left: 1.5em;
line-height: 1.8;
}
.vp-doc li {
margin: 8px 0;
}
.vp-doc li::marker {
color: var(--vp-c-brand-1);
font-weight: 600;
}
/* 任务列表 */
.vp-doc .task-list-item {
list-style-type: none;
margin-left: -1.5em;
}
.vp-doc .task-list-item input {
margin-right: 8px;
}
/* ============================================
链接样式增强
============================================ */
.vp-doc a {
text-decoration: none;
color: var(--vp-c-brand-1);
font-weight: 500;
transition: all 0.2s ease;
border-bottom: 1px solid transparent;
}
.vp-doc a:hover {
color: var(--vp-c-brand-2);
border-bottom-color: var(--vp-c-brand-2);
}
.vp-doc a code {
color: var(--vp-c-brand-1);
}
/* ============================================
首页优化
============================================ */
.VPHome {
padding-bottom: 96px;
}
.VPHero .image-bg {
opacity: 0.5;
background: linear-gradient(135deg,
var(--vp-c-brand-1) 0%,
var(--vp-c-brand-3) 100%);
}
.VPFeature {
transition: all 0.3s ease;
}
.VPFeature:hover {
transform: translateY(-4px);
box-shadow: 0 8px 24px rgba(52, 81, 178, 0.12);
}
/* ============================================
滚动条美化
============================================ */
::-webkit-scrollbar {
width: 10px;
height: 10px;
}
::-webkit-scrollbar-track {
background: var(--vp-c-bg-soft);
border-radius: 5px;
}
::-webkit-scrollbar-thumb {
background: linear-gradient(180deg,
var(--vp-c-brand-1) 0%,
var(--vp-c-brand-2) 100%);
border-radius: 5px;
transition: background 0.3s ease;
}
::-webkit-scrollbar-thumb:hover {
background: var(--vp-c-brand-2);
}
/* ============================================
移动端适配
============================================ */
@media (max-width: 768px) {
.vp-doc {
padding: 32px 20px 96px;
}
.vp-doc div[class*='language-'] > pre {
padding: 16px 20px;
font-size: 13px;
}
.vp-doc .vp-mermaid {
padding: 16px;
}
.vp-doc table th,
.vp-doc table td {
padding: 12px 16px;
}
}
/* ============================================
打印样式
============================================ */
@media print {
.VPNav,
.VPSidebar,
.VPFooter,
.giscus-container,
button.copy {
display: none !important;
}
.vp-doc div[class*='language-'] {
box-shadow: none;
border: 1px solid #e5e7eb;
}
.vp-doc table {
box-shadow: none;
border: 1px solid #e5e7eb;
}
}
/* ============================================
动画效果
============================================ */
@keyframes fadeInUp {
from {
opacity: 0;
transform: translateY(20px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
.vp-doc > * {
animation: fadeInUp 0.5s ease-out;
}
/* ============================================
无障碍优化
============================================ */
.vp-doc :focus-visible {
outline: 2px solid var(--vp-c-brand-1);
outline-offset: 2px;
border-radius: 4px;
}
/* 高对比度模式 */
@media (prefers-contrast: high) {
.vp-doc div[class*='language-'] {
border: 2px solid var(--vp-c-divider);
}
.vp-doc table {
border: 2px solid var(--vp-c-divider);
}
}
docs/.vitepress/theme/index.ts
+15
View File
@@ -0,0 +1,15 @@
import { h } from 'vue'
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import Layout from './Layout.vue'
import './custom.css'
export default {
extends: DefaultTheme,
Layout: () => {
return h(Layout)
},
enhanceApp({ app, router, siteData }) {
// 注册全局组件或插件
}
} satisfies Theme
docs/QUICK-REFERENCE.md
+261
View File
@@ -0,0 +1,261 @@
# 知识资产化系统 - 快速参考
## 系统架构
```
ljwx-qwen (源项目)
↓ publish-docs.py
ljwx-dify/knowledge/ (知识仓库)
↓ sync-knowledge.py
Dify 知识库 (向量数据库)
↓ RAG
ljwx-chat (对话系统)
```
## 核心脚本
### 1. 发布文档到 knowledge/
```bash
# 位置：ljwx-qwen/scripts/publish-docs.py
cd ljwx-qwen
python3 scripts/publish-docs.py \
--source-repo . \
--target-repo ../ljwx-dify \
--project-name ljwx-qwen \
--commit-hash $(git rev-parse HEAD)
```
### 2. 同步 knowledge/ 到 Dify
```bash
# 位置：ljwx-dify/scripts/sync-knowledge.py
cd ljwx-dify
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://localhost/v1 \
--dify-api-key $DIFY_API_KEY
```
### 3. 为文档添加元数据
```bash
# 位置：ljwx-qwen/scripts/add-frontmatter.py
cd ljwx-qwen
python3 scripts/add-frontmatter.py \
--dir docs/06-development/ \
--level L2 \
--visibility public \
--publish \
--topics spec-driven methodology
```
## 文档元数据模板
```yaml
---
asset:
level: L2 # L0/L1/L2/L3/L4
visibility: public # internal/public/mixed
publish: true # 是否发布
topics: [spec-driven, ai] # 主题标签
content:
title: 文档标题
author: brunogao
status: reviewed # draft/reviewed/public
created: 2025-01-06
updated: 2025-01-07
export:
can_publish_external: true # 可对外
requires_desensitization: false
target_formats: [blog]
---
```
## 资产层级
| 层级 | 说明 | 示例 | 对外 |
|------|------|------|------|
| L0 | 临时文档 | CI日志 | ❌ |
| L1 | 项目规格 | Feature Spec | ❌ |
| L2 | 方法论 | OpenSpec工作流 | ✅ |
| L3 | 行业方案 | 医疗系统架构 | ✅ |
| L4 | 对外内容 | 技术博客 | ✅ |
## 目录结构
```
ljwx-dify/knowledge/
├── sources/ # 原始文档（按项目）
│ └── ljwx-qwen/
│ └── docs/
├── assets/ # 资产化文档（按层级）
│ ├── L1-specs/
│ ├── L2-methodologies/
│ └── L3-solutions/
└── index/ # 索引
├── manifest.json # 全局清单
├── by-project.json # 按项目
├── by-topic.json # 按主题
└── by-level.json # 按层级
```
## 常用命令
### 查询知识库
```bash
# 查看所有项目
jq '.projects' knowledge/index/manifest.json
# 查看某个项目的文档
jq '.["ljwx-qwen"]' knowledge/index/by-project.json
# 查看某个主题的文档
jq '.["spec-driven"]' knowledge/index/by-topic.json
# 查看某个层级的文档
jq '.["L2"]' knowledge/index/by-level.json
```
### 测试发布流程
```bash
# 1. 添加元数据（dry run）
python3 scripts/add-frontmatter.py \
--dir docs/06-development/ \
--level L2 \
--publish \
--dry-run
# 2. 发布到 knowledge/（dry run）
python3 scripts/publish-docs.py \
--source-repo . \
--target-repo ../ljwx-dify \
--project-name ljwx-qwen \
--commit-hash test123
# 3. 同步到 Dify（dry run）
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://localhost/v1 \
--dify-api-key $DIFY_API_KEY \
--dry-run
```
## CI/CD 集成
### ljwx-qwen: 自动发布文档
```yaml
# .gitea/workflows/cicd.yml
publish-docs:
needs: test
runs-on: ubuntu-latest
steps:
- name: Publish docs
run: |
python scripts/publish-docs.py \
--source-repo . \
--target-repo /tmp/ljwx-dify \
--project-name ljwx-qwen \
--commit-hash ${{ github.sha }}
```
### ljwx-dify: 自动同步到 Dify
```yaml
# .gitea/workflows/sync-knowledge.yml
sync:
runs-on: ubuntu-latest
steps:
- name: Sync to Dify
run: |
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://dify-api:5001/v1 \
--dify-api-key ${{ secrets.DIFY_API_KEY }}
```
## 环境变量
```bash
# .env
DIFY_API_URL=http://localhost/v1
DIFY_API_KEY=dataset-your-api-key-here
# 使用
export $(cat .env | xargs)
```
## 故障排查
### 文档没有被发布
```bash
# 检查 frontmatter
head -20 docs/xxx.md
# 确认 publish: true
grep "publish:" docs/xxx.md
```
### 同步到 Dify 失败
```bash
# 检查 API 连接
curl http://localhost/v1/datasets \
-H "Authorization: Bearer $DIFY_API_KEY"
# 检查 Dify 服务
docker ps | grep dify
```
### 索引不一致
```bash
# 重新发布
rm -rf ../ljwx-dify/knowledge/index/*
python3 scripts/publish-docs.py \
--source-repo . \
--target-repo ../ljwx-dify \
--project-name ljwx-qwen \
--commit-hash $(git rev-parse HEAD)
```
## 关键文件
```
ljwx-docs/
├── knowledge-asset-automation-design.md # 架构设计
├── knowledge-asset-usage-guide.md # 使用指南
└── dify-knowledge-sync-guide.md # Dify同步指南
ljwx-qwen/scripts/
├── publish-docs.py # 发布脚本
└── add-frontmatter.py # 元数据工具
ljwx-dify/scripts/
└── sync-knowledge.py # Dify同步脚本
ljwx-dify/knowledge/
├── README.md # 知识库文档
└── index/ # 索引文件
```
## 下一步
1. ✅ 为更多文档添加元数据
2. ✅ 集成到 CI/CD
3. ✅ 测试完整流程
4. ⏳ 推广到其他项目
5. ⏳ 开发 Web 查询界面
6. ⏳ 实现自动脱敏工具
## 支持
- 技术支持：brunogao
- 文档：ljwx-docs/
- Issues：提交到对应项目的 issue tracker
docs/dify-knowledge-sync-guide.md
+458
View File
@@ -0,0 +1,458 @@
# Dify 知识库自动同步指南
## 概述
这个方案实现了从 `ljwx-dify/knowledge/` 目录自动同步文档到 Dify 知识库系统的完整流程。
## 架构
```
knowledge/ Dify API
├── sources/ ↓
│ └── ljwx-qwen/ → Dataset: ljwx-qwen-L2
│ └── docs/ ├── Document 1
├── assets/ ├── Document 2
│ └── L2-methodologies/ └── ...
└── index/
└── manifest.json → Dataset: ljwx-qwen-L1
├── Document 1
└── ...
```
## 核心特性
1. **按项目和层级组织**
- 每个项目的每个层级创建独立的 Dataset
- 例如：`ljwx-qwen-L2`、`ljwx-chat-L3`
2. **增量同步**
- 检测已存在的文档，避免重复创建
- 支持更新已有文档
3. **自动化**
- 可集成到 CI/CD
- 支持定时任务
4. **安全**
- 使用 Dify API Key 认证
- 支持 dry-run 模式测试
## 快速开始
### 1. 获取 Dify API Key
在 Dify 管理界面：
1. 进入 "设置" → "API Keys"
2. 创建新的 API Key
3. 复制 API Key（格式：`dataset-xxx`）
### 2. 手动测试同步
```bash
cd ljwx-dify
# Dry run 模式（不实际创建）
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://localhost/v1 \
--dify-api-key dataset-your-api-key-here \
--dry-run
# 实际同步
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://localhost/v1 \
--dify-api-key dataset-your-api-key-here
```
### 3. 只同步特定层级
```bash
# 只同步 L2 层级（方法论）
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://localhost/v1 \
--dify-api-key dataset-your-api-key-here \
--level L2
```
## 配置说明
### 环境变量
建议使用环境变量存储敏感信息：
```bash
# 创建 .env 文件
cat > .env <<EOF
DIFY_API_URL=http://localhost/v1
DIFY_API_KEY=dataset-your-api-key-here
EOF
# 使用环境变量
export $(cat .env | xargs)
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url $DIFY_API_URL \
--dify-api-key $DIFY_API_KEY
```
### API URL 配置
根据部署方式选择：
| 部署方式 | API URL |
|---------|---------|
| 本地开发 | `http://localhost/v1` |
| Docker Compose | `http://localhost:5001/v1` |
| Kubernetes | `http://dify-api.ljwx.svc:5001/v1` |
| 生产环境 | `https://dify.yourdomain.com/v1` |
## 自动化方案
### 方案1：Git Hook（推荐）
在 ljwx-dify 仓库中添加 post-merge hook：
```bash
# 创建 .git/hooks/post-merge
cat > .git/hooks/post-merge <<'EOF'
#!/bin/bash
# 检查 knowledge/ 目录是否有变更
if git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD | grep -q "^knowledge/"; then
echo "检测到 knowledge/ 目录变更，开始同步..."
cd "$(git rev-parse --show-toplevel)"
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url "${DIFY_API_URL:-http://localhost/v1}" \
--dify-api-key "${DIFY_API_KEY}" \
|| echo "同步失败，请手动检查"
fi
EOF
chmod +x .git/hooks/post-merge
```
### 方案2：CI/CD 集成
在 ljwx-dify 的 `.gitea/workflows/sync-knowledge.yml`：
```yaml
name: Sync Knowledge to Dify
on:
push:
branches: [ main ]
paths:
- 'knowledge/**'
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: 3.11
- name: Install dependencies
run: |
pip install requests pyyaml
- name: Sync to Dify
env:
DIFY_API_KEY: ${{ secrets.DIFY_API_KEY }}
run: |
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://dify-api.ljwx.svc:5001/v1 \
--dify-api-key $DIFY_API_KEY
```
### 方案3：定时任务
使用 cron 定期同步：
```bash
# 编辑 crontab
crontab -e
# 每小时同步一次
0 * * * * cd /path/to/ljwx-dify && python3 scripts/sync-knowledge.py --knowledge-dir knowledge --dify-api-url http://localhost/v1 --dify-api-key $DIFY_API_KEY >> /var/log/dify-sync.log 2>&1
```
### 方案4：Kubernetes CronJob
```yaml
apiVersion: batch/v1
kind: CronJob
metadata:
name: dify-knowledge-sync
namespace: ljwx
spec:
schedule: "0 * * * *" # 每小时
jobTemplate:
spec:
template:
spec:
containers:
- name: sync
image: python:3.11-slim
command:
- /bin/bash
- -c
- |
pip install requests pyyaml
cd /workspace
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://dify-api:5001/v1 \
--dify-api-key $DIFY_API_KEY
env:
- name: DIFY_API_KEY
valueFrom:
secretKeyRef:
name: dify-secrets
key: api-key
volumeMounts:
- name: workspace
mountPath: /workspace
volumes:
- name: workspace
gitRepo:
repository: http://gitea:3000/gao/ljwx-dify.git
revision: main
restartPolicy: OnFailure
```
## 完整工作流
### 端到端流程
```
1. 开发者在 ljwx-qwen 提交代码
↓
2. ljwx-qwen CI/CD 发布文档到 ljwx-dify/knowledge/
↓
3. ljwx-dify 检测到 knowledge/ 变更
↓
4. 触发 sync-knowledge.py
↓
5. 文档同步到 Dify 知识库
↓
6. ljwx-chat 可以检索到最新文档
```
### 示例：从提交到可用
```bash
# 1. 在 ljwx-qwen 中更新文档
cd ljwx-qwen
vim docs/06-development/new-feature.md
git add docs/
git commit -m "docs: add new feature spec"
git push origin main
# 2. CI/CD 自动发布到 ljwx-dify/knowledge/
# （publish-docs.py 自动运行）
# 3. ljwx-dify 检测到变更
cd ljwx-dify
git pull
# 4. 自动同步到 Dify（通过 Git hook 或 CI/CD）
# 或手动触发：
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://localhost/v1 \
--dify-api-key $DIFY_API_KEY
# 5. 在 ljwx-chat 中测试
# 现在可以检索到新文档了
```
## 故障排查
### 问题1：API Key 无效
```bash
# 错误信息
❌ 创建 dataset 失败: 401 Unauthorized
# 解决方案
# 1. 检查 API Key 是否正确
# 2. 确认 API Key 类型为 dataset（不是 app）
# 3. 在 Dify 管理界面重新生成
```
### 问题2：无法连接 Dify API
```bash
# 错误信息
❌ 创建 dataset 失败: Connection refused
# 解决方案
# 1. 检查 Dify 服务是否运行
docker ps | grep dify
# 2. 检查 API URL 是否正确
curl http://localhost/v1/datasets
# 3. 检查网络连接
ping dify-api.ljwx.svc
```
### 问题3：文档同步失败
```bash
# 错误信息
❌ 创建文档失败: 400 Bad Request
# 解决方案
# 1. 检查文档内容是否有效
cat knowledge/sources/ljwx-qwen/docs/xxx.md
# 2. 检查文档大小（Dify 有限制）
du -h knowledge/sources/ljwx-qwen/docs/xxx.md
# 3. 查看详细错误
python3 scripts/sync-knowledge.py --dry-run # 先测试
```
### 问题4：重复创建 Dataset
```bash
# 如果发现重复的 dataset，手动清理：
# 1. 在 Dify 管理界面删除重复的 dataset
# 2. 清空缓存重新同步
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://localhost/v1 \
--dify-api-key $DIFY_API_KEY
```
## 高级配置
### 自定义 Dataset 命名
修改 `sync-knowledge.py` 的 `get_or_create_dataset` 方法：
```python
def get_or_create_dataset(self, project_name: str, level: str) -> Optional[str]:
# 自定义命名规则
dataset_name = f"LJWX-{project_name}-{level}-Knowledge"
# ...
```
### 过滤特定文档
只同步特定主题的文档：
```python
def should_sync(self, doc_info: Dict) -> bool:
"""判断是否应该同步"""
# 只同步包含特定主题的文档
topics = doc_info.get("topics", [])
return "spec-driven" in topics or "methodology" in topics
```
### 批量处理
同步大量文档时，添加批处理和重试：
```python
import time
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
def sync_document_with_retry(self, dataset_id: str, doc_info: Dict) -> bool:
"""带重试的文档同步"""
result = self.sync_document(dataset_id, doc_info)
time.sleep(0.5) # 避免 API 限流
return result
```
## 监控和日志
### 添加日志记录
```bash
# 创建日志目录
mkdir -p logs
# 运行时记录日志
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://localhost/v1 \
--dify-api-key $DIFY_API_KEY \
2>&1 | tee logs/sync-$(date +%Y%m%d-%H%M%S).log
```
### 监控同步状态
```bash
# 查看最近的同步日志
tail -f logs/sync-*.log
# 统计同步结果
grep "✅ 成功" logs/sync-*.log | wc -l
grep "❌ 失败" logs/sync-*.log | wc -l
```
## 性能优化
### 并发同步
对于大量文档，可以使用并发：
```python
from concurrent.futures import ThreadPoolExecutor, as_completed
def sync_documents_concurrent(self, dataset_id: str, docs: List[Dict], max_workers: int = 5):
"""并发同步文档"""
with ThreadPoolExecutor(max_workers=max_workers) as executor:
futures = {
executor.submit(self.sync_document, dataset_id, doc): doc
for doc in docs
}
for future in as_completed(futures):
doc = futures[future]
try:
future.result()
except Exception as e:
print(f"❌ 同步失败 {doc['title']}: {e}")
```
### 增量同步
只同步变更的文档：
```bash
# 记录上次同步的 commit
echo $LAST_COMMIT > .last-sync-commit
# 只同步变更的文档
git diff $LAST_COMMIT HEAD --name-only | grep "^knowledge/" | while read file; do
# 同步该文档
...
done
```
## 相关文档
- [知识资产自动化发布方案](../../ljwx-docs/knowledge-asset-automation-design.md)
- [知识库 README](../knowledge/README.md)
- [Dify API 文档](https://docs.dify.ai/api-reference)
## 支持
如有问题，请联系：
- 技术支持：brunogao
- Dify 管理员：知识库团队
docs/en/QUICK-REFERENCE.md
+81
View File
@@ -0,0 +1,81 @@
# Knowledge Asset System - Quick Reference
::: warning Translation in Progress
The English translation of this document is currently in progress. Please refer to the [Chinese version](/QUICK-REFERENCE) for complete documentation.
:::
## System Architecture
```
ljwx-qwen (Source Project)
↓ publish-docs.py
ljwx-dify/knowledge/ (Knowledge Repository)
↓ sync-knowledge.py
Dify Knowledge Base (Vector Database)
↓ RAG
ljwx-chat (Chat System)
```
## Core Scripts
### 1. Publish Documents to knowledge/
```bash
# Location: ljwx-qwen/scripts/publish-docs.py
cd ljwx-qwen
python3 scripts/publish-docs.py \
--source-repo . \
--target-repo ../ljwx-dify \
--project-name ljwx-qwen \
--commit-hash $(git rev-parse HEAD)
```
### 2. Sync knowledge/ to Dify
```bash
# Location: ljwx-dify/scripts/sync-knowledge.py
cd ljwx-dify
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://localhost/v1 \
--dify-api-key $DIFY_API_KEY
```
### 3. Add Metadata to Documents
```bash
# Location: ljwx-qwen/scripts/add-frontmatter.py
cd ljwx-qwen
python3 scripts/add-frontmatter.py \
--dir docs/06-development/ \
--level L2 \
--visibility public \
--publish \
--topics spec-driven methodology
```
## Document Metadata Template
```yaml
---
asset:
level: L2 # L0/L1/L2/L3/L4
visibility: public # internal/public/mixed
publish: true # Whether to publish
topics: [spec-driven, ai] # Topic tags
content:
title: Document Title
author: brunogao
status: reviewed # draft/reviewed/public
created: 2025-01-06
updated: 2025-01-07
export:
can_publish_external: true # Can publish externally
requires_desensitization: false
target_formats: [blog]
---
```
For complete documentation, please visit the [Chinese version](/QUICK-REFERENCE).
docs/en/dify-knowledge-sync-guide.md
+72
View File
@@ -0,0 +1,72 @@
# Dify Knowledge Base Automatic Synchronization Guide
::: warning Translation in Progress
The English translation of this document is currently in progress. Please refer to the [Chinese version](/dify-knowledge-sync-guide) for complete documentation.
:::
## Overview
This solution implements a complete workflow for automatically synchronizing documents from the `ljwx-dify/knowledge/` directory to the Dify knowledge base system.
## Architecture
```
knowledge/ Dify API
├── sources/ ↓
│ └── ljwx-qwen/ → Dataset: ljwx-qwen-L2
│ └── docs/ ├── Document 1
├── assets/ ├── Document 2
│ └── L2-methodologies/ └── ...
└── index/
└── manifest.json → Dataset: ljwx-qwen-L1
├── Document 1
└── ...
```
## Core Features
1. **Organized by Project and Level**
- Create independent Dataset for each project and level
- Example: `ljwx-qwen-L2`, `ljwx-chat-L3`
2. **Incremental Sync**
- Detect existing documents to avoid duplicate creation
- Support updating existing documents
3. **Automation**
- Can be integrated into CI/CD
- Support scheduled tasks
4. **Security**
- Use Dify API Key authentication
- Support dry-run mode for testing
## Quick Start
### 1. Get Dify API Key
In the Dify admin interface:
1. Go to "Settings" → "API Keys"
2. Create a new API Key
3. Copy the API Key (format: `dataset-xxx`)
### 2. Manual Test Sync
```bash
cd ljwx-dify
# Dry run mode (no actual creation)
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://localhost/v1 \
--dify-api-key dataset-your-api-key-here \
--dry-run
# Actual sync
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://localhost/v1 \
--dify-api-key dataset-your-api-key-here
```
For complete documentation, please visit the [Chinese version](/dify-knowledge-sync-guide).
docs/en/guide/index.md
+97
View File
@@ -0,0 +1,97 @@
# Guide
Welcome to the Knowledge Asset System documentation guide. This section contains detailed design documents, usage guides, and operation manuals.
## 📚 Documentation Navigation
### Core Documents
- [Architecture Design](/en/knowledge-asset-automation-design) - System architecture and design principles
- [Usage Guide](/en/knowledge-asset-usage-guide) - Detailed usage documentation and best practices
- [Dify Sync Guide](/en/dify-knowledge-sync-guide) - Knowledge base synchronization configuration
- [Quick Reference](/en/QUICK-REFERENCE) - Common commands and configuration reference
### Quick Navigation
#### Getting Started
1. Review the [Architecture Design](/en/knowledge-asset-automation-design) to understand how the system works
2. Read the [Quick Reference](/en/QUICK-REFERENCE) to learn core commands
3. Follow the [Usage Guide](/en/knowledge-asset-usage-guide) to start practical operations
#### Advanced Usage
- Configure CI/CD automatic publishing
- Customize metadata rules
- Multi-project integration
- Dify knowledge base management
#### Troubleshooting
- Document publishing failures
- Dify synchronization errors
- Metadata validation issues
- Index inconsistency handling
## 🎯 Common Tasks
### Add Metadata to Documents
```bash
python3 scripts/add-frontmatter.py \
--dir docs/06-development/ \
--level L2 \
--visibility public \
--publish \
--topics spec-driven methodology
```
### Publish Documents to Knowledge Base
```bash
python3 scripts/publish-docs.py \
--source-repo . \
--target-repo ../ljwx-dify \
--project-name ljwx-qwen \
--commit-hash $(git rev-parse HEAD)
```
### Sync to Dify
```bash
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://localhost/v1 \
--dify-api-key $DIFY_API_KEY
```
## 💡 Best Practices
1. **Document Writing**
- Use clear heading hierarchy
- Add appropriate code examples
- Keep documentation updated
2. **Metadata Management**
- Regularly review document status
- Set visibility appropriately
- Use meaningful tags
3. **Version Control**
- Create tags for important changes
- Keep documentation in sync with code
- Reference documentation in commit messages
## 🔗 Related Resources
- [ljwx-qwen Project](http://192.168.1.83:33000/gao/ljwx-qwen)
- [ljwx-dify Knowledge Base](http://192.168.1.83:33000/gao/ljwx-dify)
- [ljwx-chat Conversation System](http://192.168.1.83:33000/gao/ljwx-chat)
## 📞 Getting Help
If you have questions:
- Check the troubleshooting section in the relevant documentation
- Contact technical support: brunogao
- Submit an issue to the corresponding project
---
**Note**: English translations of the detailed guides are in progress. Please refer to the Chinese version for complete documentation.
docs/en/index.md
+164
View File
@@ -0,0 +1,164 @@
---
layout: home
hero:
name: "LJWX Docs"
text: "Knowledge Asset System"
tagline: Automated Documentation Publishing and Knowledge Base Synchronization Solution
image:
src: /logo.svg
alt: LJWX Docs
actions:
- theme: brand
text: Quick Start
link: /en/QUICK-REFERENCE
- theme: alt
text: Architecture
link: /en/knowledge-asset-automation-design
- theme: alt
text: GitHub
link: https://github.com/ljwx
features:
- icon: 📚
title: Knowledge Asset Management
details: Transform project documentation into reusable knowledge assets through metadata-driven approach, supporting multi-dimensional organization by level, topic, and project
link: /en/knowledge-asset-automation-design
linkText: Learn Architecture
- icon: 🔄
title: Automated Publishing
details: Integrated with CI/CD pipeline, automatically publish documentation to knowledge base upon code commit, ensuring documentation stays in sync with code
link: /en/knowledge-asset-usage-guide
linkText: Usage Guide
- icon: 🤖
title: Dify Knowledge Sync
details: Automatically synchronize documents to Dify knowledge base system with incremental updates and version tracking for AI conversation systems
link: /en/dify-knowledge-sync-guide
linkText: Sync Guide
- icon: 🔍
title: Powerful Search
details: Built-in local search functionality with full-text retrieval for quick content location
linkText: Try Search
- icon: 🌓
title: Dark Mode
details: Support for light/dark theme switching, providing comfortable reading experience with automatic system theme adaptation
linkText: Switch Theme
- icon: 💬
title: Comment System
details: Integrated Giscus comment system based on GitHub Discussions for document discussion and feedback
linkText: Join Discussion
- icon: 🌐
title: Multi-language Support
details: Support for Chinese and English bilingual documentation, expandable to more languages
linkText: Switch Language
- icon: 📊
title: Metadata Management
details: Comprehensive document metadata system including asset levels, visibility, topic tags, etc., supporting fine-grained management
link: /en/QUICK-REFERENCE
linkText: Quick Reference
- icon: 🚀
title: Version Tracking
details: Each document linked to Git commit hash, traceable changes, supporting rollback to any historical version
linkText: Version Control
---
## Quick Overview
The Knowledge Asset System is a complete document management and knowledge base synchronization solution, consisting of three core components:
### 📝 Document Publishing Workflow
```mermaid
graph LR
A[Source Docs] --> B[Add Metadata]
B --> C[CI/CD Publish]
C --> D[ljwx-dify/knowledge]
D --> E[Index Update]
```
Automated publishing workflow from source project documentation to knowledge base, supporting selective publishing, version tracking, and multi-project management.
### 🔄 Knowledge Base Sync
```mermaid
graph LR
A[knowledge/] --> B[sync-knowledge.py]
B --> C[Dify API]
C --> D[Knowledge Dataset]
D --> E[AI Chat System]
```
Automatically synchronize documents to Dify knowledge base, providing knowledge support for AI conversation systems with incremental updates and multi-level management.
### 📊 Metadata System
Document metadata includes:
- **Asset Levels**: L0-L4, from temporary documents to public content
- **Visibility**: internal/public/mixed
- **Topic Tags**: spec-driven, ai-engineering, etc.
- **Version Info**: commit hash, update time, etc.
## Core Features
- ✅ **Automation First** - Git push triggers automatic publishing without manual intervention
- ✅ **Version Traceable** - Each publication records Git commit hash
- ✅ **Metadata Driven** - Control publishing strategy through YAML frontmatter
- ✅ **Multi-project Support** - Unified management of documentation from multiple projects
- ✅ **Incremental Sync** - Intelligent detection of document changes to avoid redundant operations
- ✅ **Multi-level Organization** - Organized by asset level, topic, project, and other dimensions
## Getting Started
### 1. Install Dependencies
```bash
# Clone repository
git clone https://github.com/ljwx/ljwx-docs.git
cd ljwx-docs
# Install dependencies
npm install
```
### 2. Local Development
```bash
# Start development server
npm run docs:dev
# Visit http://localhost:5173
```
### 3. Build and Deploy
```bash
# Build for production
npm run docs:build
# Preview build
npm run docs:preview
# Deploy with Node.js service
npm run docs:serve
```
## Documentation Resources
- [Quick Reference](/en/QUICK-REFERENCE) - Common commands and configuration quick reference
- [Architecture Design](/en/knowledge-asset-automation-design) - System architecture and design principles
- [Usage Guide](/en/knowledge-asset-usage-guide) - Detailed usage documentation
- [Dify Sync Guide](/en/dify-knowledge-sync-guide) - Knowledge base synchronization configuration
## Support and Feedback
- **Technical Support**: brunogao
- **Issue Reporting**: [GitHub Issues](https://github.com/ljwx/ljwx-docs/issues)
- **Documentation Contribution**: Pull Requests are welcome
docs/en/knowledge-asset-automation-design.md
+47
View File
@@ -0,0 +1,47 @@
# Knowledge Asset Automation Publishing Solution
::: warning Translation in Progress
The English translation of this document is currently in progress. Please refer to the [Chinese version](/knowledge-asset-automation-design) for complete documentation.
:::
## Architecture Overview
```
ljwx-qwen (Source Project)
├── docs/ # Project documentation
│ ├── 01-getting-started/
│ ├── 02-architecture/
│ ├── ...
│ └── 06-development/ # High-value methodologies
├── .gitea/workflows/
│ └── cicd.yml # Add documentation publishing step
└── scripts/
└── publish-docs.py # Documentation publishing script
↓
↓ (Automated publishing)
↓
ljwx-dify (Knowledge Base)
└── knowledge/ # Knowledge asset repository
├── sources/ # Original documents (organized by project)
├── assets/ # Asset documents (organized by level)
└── index/ # Indexes and metadata
```
## Core Design Principles
### 1. Version Control as Source of Truth
- Record Git commit hash for each publication
- Document changes traceable to specific commits
- Support rollback to any historical version
### 2. Metadata-Driven
- Each document must have YAML frontmatter
- Metadata determines document publishing strategy
- Support selective publishing (only publish marked documents)
### 3. Automation First
- Git push triggers automatic publishing
- No manual intervention required
- Automatic rollback on failure
For complete documentation, please visit the [Chinese version](/knowledge-asset-automation-design).
docs/en/knowledge-asset-usage-guide.md
+62
View File
@@ -0,0 +1,62 @@
# Knowledge Asset Automation Publishing - Usage Guide
::: warning Translation in Progress
The English translation of this document is currently in progress. Please refer to the [Chinese version](/knowledge-asset-usage-guide) for complete documentation.
:::
## Quick Start
### 1. Add Metadata to Existing Documents
Use `add-frontmatter.py` to batch add metadata:
```bash
# Enter project directory
cd ljwx-qwen
# Add metadata to all documents in the 06-development directory
python3 scripts/add-frontmatter.py \
--dir docs/06-development/ \
--level L2 \
--visibility public \
--publish \
--topics spec-driven methodology
# Interactive mode (confirm one by one)
python3 scripts/add-frontmatter.py \
--dir docs/06-development/ \
--level L2 \
--visibility public \
--publish \
--topics spec-driven methodology \
--interactive
```
### 2. Manual Test Publishing
```bash
# Test publishing to ljwx-dify/knowledge
python3 scripts/publish-docs.py \
--source-repo . \
--target-repo ../ljwx-dify \
--project-name ljwx-qwen \
--commit-hash $(git rev-parse HEAD)
```
### 3. View Publishing Results
```bash
# View published documents
ls -la ../ljwx-dify/knowledge/assets/L2-methodologies/ljwx-qwen/
# View index
cat ../ljwx-dify/knowledge/index/manifest.json | jq .
# Query by topic
cat ../ljwx-dify/knowledge/index/by-topic.json | jq '.["spec-driven"]'
# Query by project
cat ../ljwx-dify/knowledge/index/by-project.json | jq '.["ljwx-qwen"]'
```
For complete documentation, please visit the [Chinese version](/knowledge-asset-usage-guide).
docs/guide/index.md
+93
View File
@@ -0,0 +1,93 @@
# 指南
欢迎来到知识资产化系统文档指南。这里包含了系统的详细设计文档、使用指南和操作手册。
## 📚 文档导航
### 核心文档
- [架构设计](/knowledge-asset-automation-design) - 系统架构和设计原则
- [使用指南](/knowledge-asset-usage-guide) - 详细的使用文档和最佳实践
- [Dify 同步指南](/dify-knowledge-sync-guide) - 知识库同步配置和操作
- [快速参考](/QUICK-REFERENCE) - 常用命令和配置速查
### 快速导航
#### 新手入门
1. 了解[架构设计](/knowledge-asset-automation-design)，理解系统工作原理
2. 阅读[快速参考](/QUICK-REFERENCE)，掌握核心命令
3. 参考[使用指南](/knowledge-asset-usage-guide)，开始实际操作
#### 进阶使用
- 配置 CI/CD 自动发布
- 自定义元数据规则
- 多项目集成
- Dify 知识库管理
#### 故障排查
- 文档发布失败
- Dify 同步错误
- 元数据验证问题
- 索引不一致处理
## 🎯 常见任务
### 为文档添加元数据
```bash
python3 scripts/add-frontmatter.py \
--dir docs/06-development/ \
--level L2 \
--visibility public \
--publish \
--topics spec-driven methodology
```
### 发布文档到知识库
```bash
python3 scripts/publish-docs.py \
--source-repo . \
--target-repo ../ljwx-dify \
--project-name ljwx-qwen \
--commit-hash $(git rev-parse HEAD)
```
### 同步到 Dify
```bash
python3 scripts/sync-knowledge.py \
--knowledge-dir knowledge \
--dify-api-url http://localhost/v1 \
--dify-api-key $DIFY_API_KEY
```
## 💡 最佳实践
1. **文档编写**
- 使用清晰的标题层级
- 添加适当的代码示例
- 保持文档更新
2. **元数据管理**
- 定期审查文档状态
- 合理设置可见性
- 使用有意义的标签
3. **版本控制**
- 重要变更创建标签
- 保持文档与代码同步
- 在 commit message 中引用文档
## 🔗 相关资源
- [ljwx-qwen 项目](http://192.168.1.83:33000/gao/ljwx-qwen)
- [ljwx-dify 知识库](http://192.168.1.83:33000/gao/ljwx-dify)
- [ljwx-chat 对话系统](http://192.168.1.83:33000/gao/ljwx-chat)
## 📞 获取帮助
如有问题，请：
- 查看对应文档的故障排查部分
- 联系技术支持：brunogao
- 提交 Issue 到相应项目
docs/index.md
+164
View File
@@ -0,0 +1,164 @@
---
layout: home
hero:
name: "LJWX Docs"
text: "知识资产化系统"
tagline: 自动化文档发布与知识库同步解决方案
image:
src: /logo.svg
alt: LJWX Docs
actions:
- theme: brand
text: 快速开始
link: /QUICK-REFERENCE
- theme: alt
text: 架构设计
link: /knowledge-asset-automation-design
- theme: alt
text: GitHub
link: https://github.com/ljwx
features:
- icon: 📚
title: 知识资产化
details: 通过元数据驱动的方式，将项目文档转化为可复用的知识资产，支持按层级、主题、项目等多维度组织
link: /knowledge-asset-automation-design
linkText: 了解架构
- icon: 🔄
title: 自动化发布
details: 集成 CI/CD 流程，代码提交即自动发布文档到知识库，无需人工干预，确保文档与代码同步
link: /knowledge-asset-usage-guide
linkText: 使用指南
- icon: 🤖
title: Dify 知识库同步
details: 自动同步文档到 Dify 知识库系统，支持增量更新和版本追踪，为 AI 对话系统提供知识支撑
link: /dify-knowledge-sync-guide
linkText: 同步指南
- icon: 🔍
title: 强大的搜索
details: 内置本地搜索功能，支持全文检索，快速定位所需文档内容
linkText: 体验搜索
- icon: 🌓
title: 深色模式
details: 支持明亮/深色主题切换，提供舒适的阅读体验，自动适配系统主题
linkText: 切换主题
- icon: 💬
title: 评论系统
details: 集成 Giscus 评论系统，基于 GitHub Discussions，支持文档交流与反馈
linkText: 参与讨论
- icon: 🌐
title: 多语言支持
details: 支持中英文双语文档，可根据需要扩展更多语言
linkText: 语言切换
- icon: 📊
title: 元数据管理
details: 完善的文档元数据系统，包括资产层级、可见性、主题标签等，支持精细化管理
link: /QUICK-REFERENCE
linkText: 快速参考
- icon: 🚀
title: 版本追踪
details: 每个文档关联 Git commit hash，变更可追溯，支持回滚到任意历史版本
linkText: 版本管理
---
## 快速了解
知识资产化系统是一个完整的文档管理和知识库同步解决方案，包含三个核心部分：
### 📝 文档发布流程
```mermaid
graph LR
A[源项目文档] --> B[添加元数据]
B --> C[CI/CD 发布]
C --> D[ljwx-dify/knowledge]
D --> E[索引更新]
```
从源项目文档到知识库的自动化发布流程，支持选择性发布、版本追踪和多项目管理。
### 🔄 知识库同步
```mermaid
graph LR
A[knowledge/] --> B[sync-knowledge.py]
B --> C[Dify API]
C --> D[知识库 Dataset]
D --> E[AI 对话系统]
```
自动将文档同步到 Dify 知识库，为 AI 对话系统提供知识支撑，支持增量更新和多层级管理。
### 📊 元数据系统
文档元数据包括：
- **资产层级**：L0-L4，从临时文档到对外内容
- **可见性**：internal/public/mixed
- **主题标签**：spec-driven、ai-engineering 等
- **版本信息**：commit hash、更新时间等
## 核心特性
- ✅ **自动化优先** - Git push 触发自动发布，无需人工干预
- ✅ **版本可追溯** - 每次发布记录 Git commit hash
- ✅ **元数据驱动** - 通过 YAML frontmatter 控制发布策略
- ✅ **多项目支持** - 统一管理多个项目的文档
- ✅ **增量同步** - 智能检测文档变更，避免重复操作
- ✅ **多层级组织** - 按资产层级、主题、项目等多维度组织
## 开始使用
### 1. 安装依赖
```bash
# 克隆仓库
git clone https://github.com/ljwx/ljwx-docs.git
cd ljwx-docs
# 安装依赖
npm install
```
### 2. 本地开发
```bash
# 启动开发服务器
npm run docs:dev
# 访问 http://localhost:5173
```
### 3. 构建部署
```bash
# 构建生产版本
npm run docs:build
# 预览构建结果
npm run docs:preview
# 使用 Node.js 服务部署
npm run docs:serve
```
## 文档资源
- [快速参考](/QUICK-REFERENCE) - 常用命令和配置速查
- [架构设计](/knowledge-asset-automation-design) - 系统架构和设计原则
- [使用指南](/knowledge-asset-usage-guide) - 详细的使用文档
- [Dify 同步指南](/dify-knowledge-sync-guide) - 知识库同步配置
## 支持与反馈
- **技术支持**：brunogao
- **问题反馈**：[GitHub Issues](https://github.com/ljwx/ljwx-docs/issues)
- **文档贡献**：欢迎提交 Pull Request
docs/knowledge-asset-automation-design.md
+306
View File
@@ -0,0 +1,306 @@
# 知识资产自动化发布方案
## 架构概览
```
ljwx-qwen (源项目)
├── docs/ # 项目文档
│ ├── 01-getting-started/
│ ├── 02-architecture/
│ ├── ...
│ └── 06-development/ # 高价值方法论
├── .gitea/workflows/
│ └── cicd.yml # 添加文档发布步骤
└── scripts/
└── publish-docs.py # 文档发布脚本
↓
↓ (自动发布)
↓
ljwx-dify (知识库)
└── knowledge/ # 知识资产仓库
├── sources/ # 原始文档（按项目组织）
│ └── ljwx-qwen/
│ ├── docs/ # 镜像的文档
│ └── .metadata/ # 版本追踪
├── assets/ # 资产化文档（按层级组织）
│ ├── L1-specs/
│ ├── L2-methodologies/
│ ├── L3-solutions/
│ └── L4-public/
└── index/ # 索引和元数据
├── by-project.json
├── by-topic.json
├── by-level.json
└── manifest.json # 全局清单
```
## 核心设计原则
### 1. 版本化为真实依据
- 每次发布记录 Git commit hash
- 文档变更可追溯到具体提交
- 支持回滚到任意历史版本
### 2. 元数据驱动
- 每个文档必须有 YAML frontmatter
- 元数据决定文档的发布策略
- 支持选择性发布（只发布标记的文档）
### 3. 自动化优先
- Git push 触发自动发布
- 无需人工干预
- 失败自动回滚
## 文档元数据 Schema
### Frontmatter 格式
```yaml
---
# 资产化元数据
asset:
level: L2 # L0/L1/L2/L3/L4
visibility: public # internal/public/mixed
publish: true # 是否发布到知识库
topics: [spec-driven, openapi] # 主题标签
# 版本信息（自动生成）
version:
source_project: ljwx-qwen
source_path: docs/06-development/openspec-workflow.md
commit_hash: abc123def
commit_date: 2025-01-07T10:00:00Z
published_at: 2025-01-07T10:05:00Z
# 内容元数据
content:
title: OpenSpec 工作流程
author: brunogao
reviewer:
status: reviewed # draft/reviewed/public/deprecated
created: 2025-01-06
updated: 2025-01-07
# 对外发布配置（可选）
export:
can_publish_external: true # 是否可对外发布
requires_desensitization: false # 是否需要脱敏
target_formats: [blog, whitepaper] # 目标格式
---
# 原有文档内容...
```
## 自动发布流程
### 阶段1：文档扫描与验证
```bash
1. 扫描 docs/ 目录下所有 .md 文件
2. 解析 frontmatter 元数据
3. 验证元数据完整性
4. 筛选 publish: true 的文档
```
### 阶段2：版本信息注入
```bash
1. 获取当前 Git commit hash
2. 获取文件最后修改时间
3. 更新 version 字段
4. 生成唯一文档 ID
```
### 阶段3：发布到 ljwx-dify/knowledge
```bash
1. Clone/Pull ljwx-dify 仓库
2. 复制文档到 knowledge/sources/{project}/
3. 根据 asset.level 分类到 knowledge/assets/
4. 更新索引文件
5. Commit & Push
```
### 阶段4：索引更新
```bash
1. 更新 manifest.json（全局清单）
2. 更新 by-project.json（按项目索引）
3. 更新 by-topic.json（按主题索引）
4. 更新 by-level.json（按层级索引）
```
## CI/CD 集成
### ljwx-qwen/.gitea/workflows/cicd.yml
在现有流程中添加新的 job：
```yaml
publish-docs:
needs: test
runs-on: ubuntu-latest
if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop')
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0 # 获取完整历史
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: 3.11
- name: Install dependencies
run: |
pip install pyyaml gitpython
- name: Clone ljwx-dify repository
run: |
git clone http://192.168.1.83:33000/gao/ljwx-dify.git /tmp/ljwx-dify
- name: Publish docs to knowledge base
run: |
python scripts/publish-docs.py \
--source-repo . \
--target-repo /tmp/ljwx-dify \
--project-name ljwx-qwen \
--commit-hash ${{ github.sha }}
- name: Push to ljwx-dify
run: |
cd /tmp/ljwx-dify
git config user.name "CI Bot"
git config user.email "ci@ljwx.local"
git add knowledge/
git commit -m "docs: update knowledge from ljwx-qwen@${{ github.sha }}"
git push
```
## 脚本实现
### scripts/publish-docs.py
核心功能：
1. 扫描并解析文档
2. 验证元数据
3. 注入版本信息
4. 复制到目标仓库
5. 更新索引
### scripts/add-frontmatter.py
辅助工具：
- 批量为现有文档添加 frontmatter
- 交互式配置元数据
- 验证元数据格式
## 索引结构
### manifest.json
```json
{
"version": "1.0",
"last_updated": "2025-01-07T10:05:00Z",
"total_documents": 42,
"projects": ["ljwx-qwen", "ljwx-chat"],
"documents": [
{
"id": "ljwx-qwen-openspec-workflow-abc123",
"title": "OpenSpec 工作流程",
"source_project": "ljwx-qwen",
"source_path": "docs/06-development/openspec-workflow.md",
"asset_level": "L2",
"visibility": "public",
"topics": ["spec-driven", "openapi"],
"commit_hash": "abc123def",
"published_at": "2025-01-07T10:05:00Z"
}
]
}
```
### by-project.json
```json
{
"ljwx-qwen": {
"total": 15,
"by_level": {
"L1": 8,
"L2": 5,
"L3": 2
},
"documents": ["ljwx-qwen-openspec-workflow-abc123", ...]
}
}
```
### by-topic.json
```json
{
"spec-driven": ["ljwx-qwen-openspec-workflow-abc123", ...],
"openapi": ["ljwx-qwen-openapi-design-def456", ...]
}
```
## 使用场景
### 场景1：开发者提交代码
```bash
# 开发者正常工作
git add docs/06-development/new-feature.md
git commit -m "docs: add new feature spec"
git push origin main
# CI 自动触发
# → 测试通过
# → 构建镜像
# → 发布文档到 ljwx-dify/knowledge
# → 更新索引
```
### 场景2：批量添加元数据
```bash
# 为现有文档添加 frontmatter
python scripts/add-frontmatter.py \
--dir docs/06-development/ \
--level L2 \
--visibility public \
--publish true
```
### 场景3：查询知识库
```bash
# 在 ljwx-dify 中查询
cat knowledge/index/by-topic.json | jq '.["spec-driven"]'
# 查看某个项目的所有文档
cat knowledge/index/by-project.json | jq '.["ljwx-qwen"]'
```
## 下一步实施计划
1. ✅ 设计架构（本文档）
2. ⏳ 创建 ljwx-dify/knowledge 目录结构
3. ⏳ 实现 publish-docs.py 脚本
4. ⏳ 实现 add-frontmatter.py 脚本
5. ⏳ 为 ljwx-qwen/docs/06-development/ 添加元数据（试点）
6. ⏳ 集成到 CI/CD
7. ⏳ 测试完整流程
8. ⏳ 推广到其他项目
## 风险与缓解
### 风险1：元数据不一致
- **缓解**：CI 阶段验证元数据格式
- **缓解**：提供元数据模板和工具
### 风险2：发布失败导致 CI 阻塞
- **缓解**：文档发布失败不阻塞代码发布
- **缓解**：独立的 job，失败不影响其他步骤
### 风险3：知识库仓库冲突
- **缓解**：使用 Git pull --rebase
- **缓解**：失败时发送通知，人工介入
### 风险4：敏感信息泄露
- **缓解**：40-truth.md 强制 publish: false
- **缓解**：CI 检查敏感文件路径
- **缓解**：人工审核 public 文档
docs/knowledge-asset-usage-guide.md
+411
View File
@@ -0,0 +1,411 @@
# 知识资产自动化发布 - 使用指南
## 快速开始
### 1. 为现有文档添加元数据
使用 `add-frontmatter.py` 批量添加元数据：
```bash
# 进入项目目录
cd ljwx-qwen
# 为 06-development 目录下的所有文档添加元数据
python3 scripts/add-frontmatter.py \
--dir docs/06-development/ \
--level L2 \
--visibility public \
--publish \
--topics spec-driven methodology
# 交互模式（逐个确认）
python3 scripts/add-frontmatter.py \
--dir docs/06-development/ \
--level L2 \
--visibility public \
--publish \
--topics spec-driven methodology \
--interactive
```
### 2. 手动测试发布
```bash
# 测试发布到 ljwx-dify/knowledge
python3 scripts/publish-docs.py \
--source-repo . \
--target-repo ../ljwx-dify \
--project-name ljwx-qwen \
--commit-hash $(git rev-parse HEAD)
```
### 3. 查看发布结果
```bash
# 查看发布的文档
ls -la ../ljwx-dify/knowledge/assets/L2-methodologies/ljwx-qwen/
# 查看索引
cat ../ljwx-dify/knowledge/index/manifest.json | jq .
# 按主题查询
cat ../ljwx-dify/knowledge/index/by-topic.json | jq '.["spec-driven"]'
# 按项目查询
cat ../ljwx-dify/knowledge/index/by-project.json | jq '.["ljwx-qwen"]'
```
## 元数据配置指南
### 资产层级选择
| 层级 | 适用场景 | 示例 |
|------|---------|------|
| L0 | 临时文档、日志 | CI日志、调试记录 |
| L1 | 项目规格 | Feature Spec、API Spec |
| L2 | 方法论 | OpenSpec工作流、AI执行协议 |
| L3 | 行业方案 | 医疗系统架构、康养平台 |
| L4 | 对外内容 | 技术博客、白皮书 |
### 可见性配置
- `internal`: 仅内部使用，不对外
- `public`: 可对外发布
- `mixed`: 部分内容可对外
### 主题标签建议
常用主题标签：
- `spec-driven` - 规范驱动开发
- `openapi` - OpenAPI 相关
- `methodology` - 方法论
- `gitops` - GitOps 实践
- `ai-engineering` - AI 工程化
- `code-quality` - 代码质量
- `best-practices` - 最佳实践
- `architecture` - 架构设计
- `security` - 安全相关
- `compliance` - 合规相关
## CI/CD 集成
### 方案1：在现有 CI/CD 中添加步骤
编辑 `.gitea/workflows/cicd.yml`，添加新的 job：
```yaml
publish-docs:
needs: test
runs-on: ubuntu-latest
if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop')
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: 3.11
- name: Install dependencies
run: |
pip install pyyaml gitpython
- name: Clone ljwx-dify repository
run: |
git clone http://192.168.1.83:33000/gao/ljwx-dify.git /tmp/ljwx-dify
- name: Publish docs to knowledge base
run: |
python scripts/publish-docs.py \
--source-repo . \
--target-repo /tmp/ljwx-dify \
--project-name ljwx-qwen \
--commit-hash ${{ github.sha }}
- name: Push to ljwx-dify
run: |
cd /tmp/ljwx-dify
git config user.name "CI Bot"
git config user.email "ci@ljwx.local"
git add knowledge/
git commit -m "docs: update knowledge from ljwx-qwen@${{ github.sha }}" || echo "No changes"
git push || echo "Push failed, may need manual intervention"
```
### 方案2：独立的文档发布工作流
创建 `.gitea/workflows/publish-docs.yml`：
```yaml
name: Publish Documentation
on:
push:
branches: [ main, develop ]
paths:
- 'docs/**'
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: 3.11
- name: Install dependencies
run: |
pip install pyyaml gitpython
- name: Clone ljwx-dify repository
run: |
git clone http://192.168.1.83:33000/gao/ljwx-dify.git /tmp/ljwx-dify
- name: Publish docs
run: |
python scripts/publish-docs.py \
--source-repo . \
--target-repo /tmp/ljwx-dify \
--project-name ljwx-qwen \
--commit-hash ${{ github.sha }}
- name: Push to ljwx-dify
run: |
cd /tmp/ljwx-dify
git config user.name "CI Bot"
git config user.email "ci@ljwx.local"
git add knowledge/
git commit -m "docs: update knowledge from ljwx-qwen@${{ github.sha }}" || echo "No changes"
git push || echo "Push failed"
```
## 常见场景
### 场景1：新项目接入
1. 复制脚本到新项目：
```bash
cp ljwx-qwen/scripts/publish-docs.py new-project/scripts/
cp ljwx-qwen/scripts/add-frontmatter.py new-project/scripts/
```
2. 为文档添加元数据：
```bash
cd new-project
python3 scripts/add-frontmatter.py \
--dir docs/ \
--level L1 \
--visibility internal \
--publish \
--interactive
```
3. 配置 CI/CD（参考上面的方案）
4. 测试发布：
```bash
python3 scripts/publish-docs.py \
--source-repo . \
--target-repo ../ljwx-dify \
--project-name new-project \
--commit-hash $(git rev-parse HEAD)
```
### 场景2：批量更新元数据
如果需要修改已有文档的元数据：
```bash
# 1. 使用脚本批量更新（会覆盖现有 frontmatter）
python3 scripts/add-frontmatter.py \
--dir docs/06-development/ \
--level L2 \
--visibility public \
--publish \
--topics spec-driven methodology ai-engineering
# 2. 或者手动编辑文档的 frontmatter
vim docs/06-development/openspec-workflow.md
```
### 场景3：选择性发布
只发布特定目录的文档：
```bash
# 方法1：只为需要发布的文档设置 publish: true
python3 scripts/add-frontmatter.py \
--dir docs/06-development/ \
--publish # 其他目录不加 --publish
# 方法2：修改 publish-docs.py，添加路径过滤
# （需要修改脚本代码）
```
### 场景4：查询知识库
```bash
# 查看所有项目
cat ../ljwx-dify/knowledge/index/by-project.json | jq 'keys'
# 查看某个项目的文档数量
cat ../ljwx-dify/knowledge/index/by-project.json | jq '.["ljwx-qwen"].total'
# 查看所有主题
cat ../ljwx-dify/knowledge/index/by-topic.json | jq 'keys'
# 查看某个主题的所有文档
cat ../ljwx-dify/knowledge/index/by-topic.json | jq '.["spec-driven"]'
# 查看某个文档的完整信息
cat ../ljwx-dify/knowledge/index/manifest.json | jq '.documents[] | select(.id == "ljwx-qwen-openspec-workflow-test123")'
```
## 故障排查
### 问题1：脚本执行失败
```bash
# 检查 Python 版本
python3 --version # 需要 3.11+
# 安装依赖
pip install pyyaml gitpython
# 检查脚本权限
chmod +x scripts/publish-docs.py
chmod +x scripts/add-frontmatter.py
```
### 问题2：没有文档被发布
检查：
1. 文档是否有 frontmatter？
2. `asset.publish` 是否为 `true`？
3. frontmatter 格式是否正确？
```bash
# 验证 YAML 格式
python3 -c "import yaml; yaml.safe_load(open('docs/xxx.md').read().split('---')[1])"
```
### 问题3：索引不一致
重新发布所有文档：
```bash
# 清空索引
rm -rf ../ljwx-dify/knowledge/index/*
# 重新发布
python3 scripts/publish-docs.py \
--source-repo . \
--target-repo ../ljwx-dify \
--project-name ljwx-qwen \
--commit-hash $(git rev-parse HEAD)
```
### 问题4：Git 冲突
如果多个项目同时发布导致冲突：
```bash
cd ../ljwx-dify
git pull --rebase
# 解决冲突
git add knowledge/
git rebase --continue
git push
```
## 最佳实践
### 1. 文档编写规范
- 每个文档必须有清晰的标题
- 使用 Markdown 标准格式
- 避免硬编码敏感信息
- 添加适当的主题标签
### 2. 元数据管理
- 定期审查文档的 `status` 字段
- 及时更新 `updated` 日期
- 为重要文档指定 `reviewer`
- 合理设置 `visibility`
### 3. 版本控制
- 重要变更创建 Git tag
- 在 commit message 中引用文档
- 保持文档和代码同步更新
### 4. 安全检查
- 定期审查 `visibility: public` 的文档
- 确保 40-truth.md 不被发布
- 检查是否有敏感信息泄露
## 进阶功能
### 自定义发布规则
修改 `publish-docs.py` 的 `should_publish` 方法：
```python
def should_publish(self, frontmatter: Optional[Dict]) -> bool:
"""判断文档是否应该发布"""
if not frontmatter:
return False
asset = frontmatter.get("asset", {})
# 自定义规则
if not asset.get("publish", False):
return False
# 只发布 reviewed 状态的文档
content = frontmatter.get("content", {})
if content.get("status") != "reviewed":
return False
return True
```
### 添加发布钩子
在发布前/后执行自定义操作：
```python
# 在 DocumentPublisher 类中添加
def pre_publish_hook(self, doc_path: Path):
"""发布前钩子"""
# 例如：检查敏感信息
pass
def post_publish_hook(self, doc_path: Path):
"""发布后钩子"""
# 例如：发送通知
pass
```
## 相关文档
- [知识资产自动化发布方案](knowledge-asset-automation-design.md)
- [ljwx-dify 知识库 README](../ljwx-dify/knowledge/README.md)
- [ljwx-qwen 文档规范](../ljwx-qwen/docs/08-reference/01-documentation-structure.md)
## 支持
如有问题，请联系：
- 技术支持：brunogao
- 文档维护：知识库团队
docs/public/logo.svg
+38
View File
@@ -0,0 +1,38 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" width="200" height="200">
<!-- LJWX Logo -->
<defs>
<linearGradient id="gradient" x1="0%" y1="0%" x2="100%" y2="100%">
<stop offset="0%" style="stop-color:#3451b2;stop-opacity:1" />
<stop offset="100%" style="stop-color:#5672cd;stop-opacity:1" />
</linearGradient>
</defs>
<!-- Background circle -->
<circle cx="100" cy="100" r="90" fill="url(#gradient)" opacity="0.1"/>
<!-- Book icon representing documentation -->
<path d="M 50 60 L 50 140 L 150 140 L 150 60 Z"
fill="none"
stroke="url(#gradient)"
stroke-width="4"
stroke-linejoin="round"/>
<!-- Pages -->
<line x1="70" y1="60" x2="70" y2="140"
stroke="url(#gradient)"
stroke-width="2"/>
<!-- Text lines -->
<line x1="85" y1="80" x2="135" y2="80"
stroke="url(#gradient)"
stroke-width="3"
stroke-linecap="round"/>
<line x1="85" y1="100" x2="135" y2="100"
stroke="url(#gradient)"
stroke-width="3"
stroke-linecap="round"/>
<line x1="85" y1="120" x2="120" y2="120"
stroke="url(#gradient)"
stroke-width="3"
stroke-linecap="round"/>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.2 KiB

package.json
+34
View File
@@ -0,0 +1,34 @@
{
"name": "ljwx-docs",
"version": "1.0.0",
"description": "知识资产化系统文档站点",
"type": "module",
"scripts": {
"dev": "vitepress dev docs --port 5555 --host 0.0.0.0",
"build": "vitepress build docs",
"preview": "vitepress preview docs --port 5555 --host 0.0.0.0",
"start": "vitepress dev docs --port 5555 --host 0.0.0.0",
"serve": "node server.js",
"docs:dev": "vitepress dev docs --port 5555 --host 0.0.0.0",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs --port 5555 --host 0.0.0.0",
"docs:serve": "node server.js"
},
"keywords": [
"knowledge-management",
"documentation",
"dify",
"vitepress"
],
"author": "brunogao",
"license": "MIT",
"devDependencies": {
"vitepress": "^1.0.1",
"vue": "^3.4.19"
},
"dependencies": {
"express": "^4.18.2",
"compression": "^1.7.4",
"sirv": "^2.0.4"
}
}
server.js
+94
View File
@@ -0,0 +1,94 @@
import express from 'express'
import compression from 'compression'
import sirv from 'sirv'
import { fileURLToPath } from 'url'
import { dirname, join } from 'path'
import { existsSync } from 'fs'
const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)
const app = express()
const PORT = process.env.PORT || 5555
const HOST = process.env.HOST || '0.0.0.0'
// 检查构建目录是否存在
const distPath = join(__dirname, 'dist')
if (!existsSync(distPath)) {
console.error('❌ Error: dist directory not found!')
console.error('Please run "npm run docs:build" first to build the documentation.')
process.exit(1)
}
// 启用 Gzip 压缩
app.use(compression())
// 添加安全响应头
app.use((req, res, next) => {
res.setHeader('X-Content-Type-Options', 'nosniff')
res.setHeader('X-Frame-Options', 'DENY')
res.setHeader('X-XSS-Protection', '1; mode=block')
next()
})
// 静态文件服务
const serve = sirv(distPath, {
etag: true,
maxAge: 31536000, // 1 year for immutable assets
immutable: true,
gzip: true,
brotli: true,
setHeaders: (res, pathname) => {
// HTML 文件不缓存，确保内容更新
if (pathname.endsWith('.html')) {
res.setHeader('Cache-Control', 'no-cache, must-revalidate')
}
// 静态资源长期缓存
else if (pathname.match(/\.(js|css|png|jpg|jpeg|gif|svg|woff|woff2|ttf|eot|ico)$/)) {
res.setHeader('Cache-Control', 'public, max-age=31536000, immutable')
}
}
})
app.use(serve)
// SPA 回退处理
app.get('*', (req, res) => {
res.sendFile(join(distPath, 'index.html'))
})
// 错误处理
app.use((err, req, res, next) => {
console.error('Server error:', err)
res.status(500).send('Internal Server Error')
})
// 优雅关闭
const server = app.listen(PORT, HOST, () => {
console.log('┌─────────────────────────────────────────────┐')
console.log('│ │')
console.log('│ 🚀 LJWX Docs Server Started │')
console.log('│ │')
console.log(`│ ➜ Local: http://localhost:${PORT} │`)
console.log(`│ ➜ Network: http://${HOST}:${PORT} │`)
console.log('│ │')
console.log('│ Press Ctrl+C to stop │')
console.log('│ │')
console.log('└─────────────────────────────────────────────┘')
})
process.on('SIGTERM', () => {
console.log('\n⏳ SIGTERM signal received: closing HTTP server')
server.close(() => {
console.log('✅ HTTP server closed')
process.exit(0)
})
})
process.on('SIGINT', () => {
console.log('\n⏳ SIGINT signal received: closing HTTP server')
server.close(() => {
console.log('✅ HTTP server closed')
process.exit(0)
})
})