docs: add upage usage instructions document
This commit is contained in:
LIlGG
38
.env.example
38
.env.example
@@ -93,7 +93,7 @@ PERPLEXITY_API_KEY=
|
||||
# {"region": "us-east-1", "accessKeyId": "yourAccessKeyId", "secretAccessKey": "yourSecretAccessKey", "sessionToken": "yourSessionToken"}
|
||||
AWS_BEDROCK_CONFIG=
|
||||
|
||||
# 是否开启文件日志
|
||||
# Whether to enable file logging
|
||||
USAGE_LOG_FILE=false
|
||||
# Include this environment variable if you want more logging for debugging locally
|
||||
LOG_LEVEL=debug
|
||||
@@ -109,34 +109,34 @@ WEATHER_API_KEY=
|
||||
# Default LLM provider to use (e.g.,OpenAILike,OpenAI, Anthropic, Mistral)
|
||||
LLM_DEFAULT_PROVIDER=
|
||||
|
||||
# 生成页面所使用的 MODEL（应该与 LLM_DEFAULT_PROVIDER 相对应）
|
||||
# The MODEL used to generate the page (should correspond to LLM_DEFAULT_PROVIDER)
|
||||
LLM_DEFAULT_MODEL=
|
||||
|
||||
# 用于辅助页面生成所使用的 MODEL，例如总结和预分析。（应该与 LLM_DEFAULT_PROVIDER 相对应）
|
||||
# Used for the MODEL assisting page generation, such as summary and pre-analysis. (Should correspond to LLM_DEFAULT_PROVIDER.)
|
||||
LLM_MINOR_MODEL=
|
||||
|
||||
# Comma-separated list of enabled providers (empty means all providers)
|
||||
# Example: OpenAILike,OpenAI,Anthropic,Mistral
|
||||
LLM_ENABLED_PROVIDERS=
|
||||
|
||||
# Logto 集成所需环境变量
|
||||
# Logto 地址
|
||||
LOGTO_ENDPOINT=
|
||||
# Logto 应用 ID
|
||||
LOGTO_APP_ID=
|
||||
# Logto 应用密钥
|
||||
LOGTO_APP_SECRET=
|
||||
# 应用基础 URL，根据实际部署环境修改
|
||||
LOGTO_BASE_URL=http://localhost:5173
|
||||
# 随机任意的 36 位字符串，用于加密 Logto 的 cookie。
|
||||
LOGTO_COOKIE_SECRET=
|
||||
# 是否在开发环境中启用 Logto 认证，设置为 false 则在开发环境不强制认证
|
||||
# Logto integration required environment variables
|
||||
# Whether to enable Logto authentication
|
||||
LOGTO_ENABLE=false
|
||||
# 运行环境，与 NODE_ENV 有所不同， NODE_ENV 在打包时就已确定，而此变量用于某些功能在不同环境下的开放
|
||||
# Logto Address
|
||||
LOGTO_ENDPOINT=
|
||||
# Logto Application ID
|
||||
LOGTO_APP_ID=
|
||||
# Logto Application secret
|
||||
LOGTO_APP_SECRET=
|
||||
# Application base URL, modify according to the actual deployment environment
|
||||
LOGTO_BASE_URL=http://localhost:5173
|
||||
# A random 36-character string used for encrypting Logto cookies.
|
||||
LOGTO_COOKIE_SECRET=
|
||||
|
||||
# Runtime environment, which differs from NODE_ENV. NODE_ENV is determined at build time, whereas this variable is used to enable certain features in different environments.
|
||||
# development | production | test
|
||||
OPERATING_ENV=production
|
||||
|
||||
# 资源文件存储位置
|
||||
# Resource file storage location
|
||||
STORAGE_DIR=/public/uploads
|
||||
# 附件上传的最大大小
|
||||
# Maximum size for attachment upload
|
||||
MAX_UPLOAD_SIZE_MB=5
|
||||
|
||||
2
.github/workflows/ci.yaml
vendored
2
.github/workflows/ci.yaml
vendored
@@ -3,7 +3,7 @@ name: CI/CD
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
- main
|
||||
pull_request:
|
||||
|
||||
jobs:
|
||||
|
||||
27
.github/workflows/docs.yaml
vendored
27
.github/workflows/docs.yaml
vendored
@@ -5,32 +5,37 @@ on:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- 'docs/**' # This will only trigger the workflow when files in docs directory change
|
||||
- 'docs/**'
|
||||
permissions:
|
||||
contents: write
|
||||
jobs:
|
||||
build_docs:
|
||||
runs-on: ubuntu-latest
|
||||
defaults:
|
||||
run:
|
||||
working-directory: ./docs
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Configure Git Credentials
|
||||
run: |
|
||||
git config user.name github-actions[bot]
|
||||
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
|
||||
- uses: actions/setup-node@v4
|
||||
|
||||
- name: Setup pnpm
|
||||
uses: pnpm/action-setup@v4
|
||||
with:
|
||||
node-version: 18
|
||||
cache: npm
|
||||
cache-dependency-path: docs/package-lock.json
|
||||
version: '9.4.0'
|
||||
run_install: false
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20.15.1'
|
||||
cache: pnpm
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
run: pnpm install --filter upage-docs...
|
||||
|
||||
- name: Build website
|
||||
run: npm run build
|
||||
- name: Build docs website
|
||||
run: pnpm run docs:build
|
||||
|
||||
- name: Deploy to GitHub Pages
|
||||
uses: peaceiris/actions-gh-pages@v3
|
||||
|
||||
@@ -1,15 +1,14 @@
|
||||
import { LLMManager } from '~/lib/modules/llm/manager';
|
||||
|
||||
export const WORK_DIR_NAME = 'project';
|
||||
export const MODEL_REGEX = /^\[Model: (.*?)\]\n\n/;
|
||||
export const PROVIDER_REGEX = /\[Provider: (.*?)\]\n\n/;
|
||||
|
||||
const llmManager = LLMManager.getInstance();
|
||||
|
||||
export const DEFAULT_MODEL = llmManager.getDefaultModel();
|
||||
export const MINOR_MODEL = llmManager.getMinorModel();
|
||||
export const PROVIDER_LIST = llmManager.getAllProviders();
|
||||
export const DEFAULT_PROVIDER = llmManager.getDefaultProvider();
|
||||
export const DEFAULT_MODEL = llmManager.getDefaultModel();
|
||||
export const MINOR_MODEL = llmManager.getMinorModel();
|
||||
|
||||
export const DEFAULT_MODEL_DETAILS = DEFAULT_PROVIDER.staticModels.find((m) => m.name === DEFAULT_MODEL);
|
||||
export const MINOR_MODEL_DETAILS = DEFAULT_PROVIDER.staticModels.find((m) => m.name === MINOR_MODEL);
|
||||
|
||||
@@ -1,115 +0,0 @@
|
||||
---
|
||||
id: changelog
|
||||
title: 更新日志
|
||||
---
|
||||
|
||||
# 更新日志
|
||||
|
||||
本文档记录了 UPage 的版本更新历史，包括新功能、改进和修复的问题。
|
||||
|
||||
## 1.0.0 (2025-09-15)
|
||||
|
||||
### 🚀 新功能
|
||||
|
||||
- **AI 页面生成**：基于自然语言描述生成完整网页
|
||||
- **多 AI 提供商支持**：
|
||||
- OpenAI (GPT-3.5/GPT-4)
|
||||
- Anthropic Claude
|
||||
- Google Gemini
|
||||
- 兼容 OpenAI 接口的服务
|
||||
- Ollama (本地模型)
|
||||
- **可视化编辑器**：拖拽式页面编辑器，实时预览
|
||||
- **组件库**：丰富的预设组件，包括布局、表单、媒体等
|
||||
- **响应式设计**：自动适应不同屏幕尺寸
|
||||
- **主题系统**：内置多种主题，支持自定义
|
||||
- **页面管理**：创建、编辑、复制、删除页面
|
||||
- **版本历史**：自动保存页面版本，支持回滚
|
||||
- **导出功能**：导出为 HTML/CSS/JS、ZIP、JSON 或 PDF
|
||||
- **部署集成**：
|
||||
- Vercel 部署支持
|
||||
- Netlify 部署支持
|
||||
- **用户认证**：通过 Logto 实现用户认证和权限管理
|
||||
- **Docker 部署**：提供官方 Docker 镜像和 Docker Compose 配置
|
||||
|
||||
### 🔧 技术栈
|
||||
|
||||
- **前端**：React、TypeScript、Vite、UnoCSS
|
||||
- **后端**：Node.js、Express、Remix
|
||||
- **数据库**：SQLite
|
||||
- **AI 集成**：AI SDK、各大 AI 提供商 API
|
||||
- **部署**：Docker、GitHub Actions
|
||||
|
||||
## 0.9.0 (2025-08-20)
|
||||
|
||||
### 🚀 新功能
|
||||
|
||||
- **Beta 版本发布**：首个公开测试版本
|
||||
- **核心功能实现**：
|
||||
- AI 页面生成
|
||||
- 可视化编辑器
|
||||
- 页面管理
|
||||
- 导出功能
|
||||
- **Docker 部署支持**：提供 Docker 镜像和部署指南
|
||||
- **文档系统**：基本使用文档和部署指南
|
||||
|
||||
### 🐛 修复
|
||||
|
||||
- 修复页面生成时的布局问题
|
||||
- 修复组件拖拽在某些浏览器中的兼容性问题
|
||||
- 修复导出功能中的资源路径问题
|
||||
|
||||
## 0.8.0 (2025-07-15)
|
||||
|
||||
### 🚀 新功能
|
||||
|
||||
- **Alpha 版本**：内部测试版本
|
||||
- **概念验证**：
|
||||
- AI 生成基本页面结构
|
||||
- 简单的可视化编辑
|
||||
- 基本的导出功能
|
||||
- **技术选型确定**：
|
||||
- 前端框架和库
|
||||
- AI 集成方案
|
||||
- 部署策略
|
||||
|
||||
### 📝 计划
|
||||
|
||||
- 完善 AI 生成功能
|
||||
- 增强可视化编辑器
|
||||
- 添加更多组件和模板
|
||||
- 实现部署集成
|
||||
- 准备公开测试版本
|
||||
|
||||
## 未来计划
|
||||
|
||||
以下是 UPage 计划在未来版本中实现的功能：
|
||||
|
||||
### 近期计划 (1.x)
|
||||
|
||||
- **协作功能**：多用户同时编辑页面
|
||||
- **评论和反馈**：页面内评论和反馈系统
|
||||
- **更多组件**：扩展组件库，添加更多高级组件
|
||||
- **自定义主题编辑器**：可视化主题编辑工具
|
||||
- **更多 AI 提供商支持**：增加对更多 AI 模型的支持
|
||||
- **性能优化**：提升页面生成和编辑的性能
|
||||
- **移动端编辑器**：支持在移动设备上编辑页面
|
||||
|
||||
### 中期计划 (2.x)
|
||||
|
||||
- **插件系统**：支持第三方插件扩展功能
|
||||
- **高级动画**：更丰富的页面动画效果
|
||||
- **数据集成**：与外部数据源集成
|
||||
- **多语言支持**：界面和生成内容的多语言支持
|
||||
- **AI 辅助编程**：生成自定义组件和交互逻辑
|
||||
- **高级分析**：页面性能和访问分析
|
||||
- **A/B 测试**：内置 A/B 测试功能
|
||||
|
||||
### 长期愿景
|
||||
|
||||
- **完整网站生成**：从描述生成完整多页面网站
|
||||
- **智能内容管理**：AI 辅助的内容创建和管理
|
||||
- **无代码应用构建**：扩展至应用程序构建
|
||||
- **生态系统**：建立开发者和设计师社区
|
||||
- **企业级功能**：满足大型组织的需求
|
||||
|
||||
我们欢迎社区参与和贡献，共同推动 UPage 的发展。如果您有功能建议或发现问题，请在 [GitHub Issues](https://github.com/halo-dev/upage/issues) 中提出。
|
||||
@@ -1,199 +0,0 @@
|
||||
---
|
||||
id: contributing
|
||||
title: 贡献指南
|
||||
---
|
||||
|
||||
# 贡献指南
|
||||
|
||||
感谢您对 UPage 项目的关注！我们非常欢迎各种形式的贡献，无论是功能开发、bug 修复、文档改进还是使用反馈。本指南将帮助您了解如何参与 UPage 的开发和贡献。
|
||||
|
||||
## 行为准则
|
||||
|
||||
参与 UPage 项目的所有贡献者都应遵循以下行为准则：
|
||||
|
||||
- 尊重所有参与者，无论其背景、经验或观点
|
||||
- 接受建设性的批评和反馈
|
||||
- 专注于对社区最有利的事情
|
||||
- 展现同理心和善意
|
||||
|
||||
## 贡献方式
|
||||
|
||||
您可以通过多种方式为 UPage 做出贡献：
|
||||
|
||||
### 报告问题
|
||||
|
||||
如果您发现了 bug 或有功能建议，请在 [GitHub Issues](https://github.com/halo-dev/upage/issues) 中提出。提交问题时，请尽可能提供以下信息：
|
||||
|
||||
- 清晰的问题描述
|
||||
- 复现步骤
|
||||
- 预期行为与实际行为
|
||||
- 截图（如适用）
|
||||
- 环境信息（浏览器、操作系统、UPage 版本等）
|
||||
|
||||
### 提交代码
|
||||
|
||||
如果您想直接贡献代码，请遵循以下步骤：
|
||||
|
||||
1. Fork 项目仓库
|
||||
2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`)
|
||||
3. 提交您的更改 (`git commit -m 'Add some amazing feature'`)
|
||||
4. 推送到分支 (`git push origin feature/amazing-feature`)
|
||||
5. 创建 Pull Request
|
||||
|
||||
### 改进文档
|
||||
|
||||
文档对于任何项目都至关重要。您可以通过以下方式改进 UPage 的文档：
|
||||
|
||||
- 修复文档中的错误或不准确之处
|
||||
- 添加缺失的信息或示例
|
||||
- 改进文档的结构和可读性
|
||||
- 翻译文档到其他语言
|
||||
|
||||
### 分享和推广
|
||||
|
||||
您也可以通过以下方式支持 UPage：
|
||||
|
||||
- 在社交媒体上分享项目
|
||||
- 撰写关于 UPage 的博客文章或教程
|
||||
- 在相关论坛和社区中推荐 UPage
|
||||
- 为项目加星标（Star）
|
||||
|
||||
## 开发环境设置
|
||||
|
||||
### 前置条件
|
||||
|
||||
开始开发 UPage 前，请确保您的系统满足以下要求：
|
||||
|
||||
- Node.js 18.18.0 或更高版本
|
||||
- pnpm 9.4.0 或更高版本
|
||||
- Git
|
||||
|
||||
### 克隆仓库
|
||||
|
||||
```bash
|
||||
git clone https://github.com/halo-dev/upage.git
|
||||
cd upage
|
||||
```
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 启动开发服务器
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
此命令会启动开发服务器，您可以通过 `http://localhost:3000` 访问。
|
||||
|
||||
### 构建项目
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
pnpm test
|
||||
```
|
||||
|
||||
## 代码规范
|
||||
|
||||
### JavaScript/TypeScript 规范
|
||||
|
||||
UPage 使用 [Biome](https://biomejs.dev/) 进行代码格式化和 linting。在提交代码前，请确保您的代码符合项目的代码规范：
|
||||
|
||||
```bash
|
||||
pnpm check
|
||||
```
|
||||
|
||||
您也可以使用以下命令自动修复格式问题：
|
||||
|
||||
```bash
|
||||
pnpm check --write
|
||||
```
|
||||
|
||||
### Git 提交规范
|
||||
|
||||
我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范来格式化 Git 提交信息。提交信息应遵循以下格式：
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
常用的 `type` 包括：
|
||||
|
||||
- `feat`: 新功能
|
||||
- `fix`: 修复 bug
|
||||
- `docs`: 文档更新
|
||||
- `style`: 代码风格更改（不影响代码功能）
|
||||
- `refactor`: 代码重构
|
||||
- `perf`: 性能优化
|
||||
- `test`: 添加或修改测试
|
||||
- `chore`: 构建过程或辅助工具的变动
|
||||
|
||||
例如：
|
||||
|
||||
```
|
||||
feat(editor): 添加拖拽调整组件大小功能
|
||||
|
||||
添加了一个新的拖拽句柄，允许用户直接调整组件的大小。
|
||||
同时优化了调整过程中的性能。
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
## 分支策略
|
||||
|
||||
- `main`: 主分支，包含稳定的代码
|
||||
- `develop`: 开发分支，包含最新的开发代码
|
||||
- `feature/*`: 功能分支，用于开发新功能
|
||||
- `fix/*`: 修复分支，用于修复 bug
|
||||
- `release/*`: 发布分支，用于准备新版本发布
|
||||
|
||||
请基于 `develop` 分支创建您的功能或修复分支，并在完成后向 `develop` 分支提交 Pull Request。
|
||||
|
||||
## Pull Request 流程
|
||||
|
||||
1. 确保您的代码符合项目的代码规范
|
||||
2. 更新相关文档（如适用）
|
||||
3. 添加或更新测试（如适用）
|
||||
4. 确保所有测试通过
|
||||
5. 提交 Pull Request 到 `develop` 分支
|
||||
6. 在 PR 描述中详细说明您的更改
|
||||
|
||||
## 版本发布流程
|
||||
|
||||
UPage 遵循 [语义化版本控制](https://semver.org/) 规范。版本号格式为 `X.Y.Z`：
|
||||
|
||||
- `X`: 主版本号，当进行不兼容的 API 更改时递增
|
||||
- `Y`: 次版本号，当添加向后兼容的功能时递增
|
||||
- `Z`: 修订号，当进行向后兼容的 bug 修复时递增
|
||||
|
||||
## 文档贡献
|
||||
|
||||
UPage 的文档使用 [Docusaurus](https://docusaurus.io/) 构建。如果您想贡献文档，请遵循以下步骤：
|
||||
|
||||
1. 在 `docs` 目录中找到相关的 Markdown 文件
|
||||
2. 进行必要的更改
|
||||
3. 在本地预览更改：`pnpm docs:start`
|
||||
4. 提交 Pull Request
|
||||
|
||||
## 社区
|
||||
|
||||
加入 UPage 社区，与其他贡献者交流：
|
||||
|
||||
- [GitHub Discussions](https://github.com/halo-dev/upage/discussions)
|
||||
- [GitHub Issues](https://github.com/halo-dev/upage/issues)
|
||||
|
||||
## 许可证
|
||||
|
||||
UPage 采用 [MIT 许可证](https://github.com/halo-dev/upage/blob/main/LICENSE)。通过贡献代码，您同意您的贡献将在相同的许可证下发布。
|
||||
47
docs/content/contributing/code-of-conduct.md
Normal file
47
docs/content/contributing/code-of-conduct.md
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
id: code-of-conduct
|
||||
title: 行为准则
|
||||
---
|
||||
|
||||
# 行为准则
|
||||
|
||||
UPage 项目致力于为所有贡献者和参与者提供一个友好、安全和包容的环境。我们希望每个人都能够在没有骚扰和歧视的情况下参与项目。
|
||||
|
||||
## 我们的标准
|
||||
|
||||
参与 UPage 项目的所有贡献者都应遵循以下行为准则：
|
||||
|
||||
- **尊重所有参与者**，无论其背景、经验或观点
|
||||
- **接受建设性的批评和反馈**，并以专业和尊重的方式回应
|
||||
- **专注于对社区最有利的事情**，考虑项目和用户的长期利益
|
||||
- **展现同理心和善意**，理解他人的观点和立场
|
||||
|
||||
## 不可接受的行为
|
||||
|
||||
以下行为被视为不可接受：
|
||||
|
||||
- 使用性暗示的语言或图像
|
||||
- 人身攻击、侮辱或贬低性评论
|
||||
- 公开或私下的骚扰
|
||||
- 未经明确许可发布他人的私人信息
|
||||
- 任何其他可能被合理认为不适当或冒犯的行为
|
||||
|
||||
## 责任
|
||||
|
||||
项目维护者有责任明确行为标准，并对任何不可接受行为采取适当和公正的纠正措施。
|
||||
|
||||
项目维护者有权和责任删除、编辑或拒绝与本行为准则不符的评论、提交、代码、问题和其他贡献，并在适当时暂时或永久禁止任何贡献者参与项目。
|
||||
|
||||
## 范围
|
||||
|
||||
本行为准则适用于所有项目空间，包括但不限于 GitHub 仓库、问题跟踪器、讨论区、社交媒体和公共活动。它也适用于个人在代表项目或其社区时的行为。
|
||||
|
||||
## 反馈
|
||||
|
||||
如果您遇到滥用、骚扰或其他不可接受的行为，请通过 [GitHub Issues](https://github.com/halo-dev/upage/issues) 或直接联系项目维护者报告。
|
||||
|
||||
所有投诉将被审查和调查，并将导致被认为必要和适当的回应。项目维护者有义务对报告事件的人保密。
|
||||
|
||||
## 参考
|
||||
|
||||
本行为准则改编自 [Contributor Covenant](https://www.contributor-covenant.org)，版本 2.0，可在 [https://www.contributor-covenant.org/version/2/0/code_of_conduct.html](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html) 查阅。
|
||||
156
docs/content/contributing/code-standards.md
Normal file
156
docs/content/contributing/code-standards.md
Normal file
@@ -0,0 +1,156 @@
|
||||
---
|
||||
id: code-standards
|
||||
title: 代码规范
|
||||
---
|
||||
|
||||
# 代码规范
|
||||
|
||||
UPage 项目遵循严格的代码规范和最佳实践，以确保代码质量和一致性。本文档概述了这些规范，所有贡献者在提交代码前应确保遵循这些规范。
|
||||
|
||||
## JavaScript/TypeScript 规范
|
||||
|
||||
UPage 使用 [Biome](https://biomejs.dev/) 进行代码格式化和 linting。Biome 是一个快速的代码格式化工具和 linter，可以帮助我们保持代码风格的一致性。
|
||||
|
||||
### 代码检查
|
||||
|
||||
在提交代码前，请确保您的代码符合项目的代码规范：
|
||||
|
||||
```bash
|
||||
pnpm check
|
||||
```
|
||||
|
||||
### 自动修复
|
||||
|
||||
您也可以使用以下命令自动修复格式问题：
|
||||
|
||||
```bash
|
||||
pnpm check --write
|
||||
```
|
||||
|
||||
### 主要规范
|
||||
|
||||
- **缩进**: 使用 2 个空格
|
||||
- **分号**: 必须使用分号
|
||||
- **引号**: 使用单引号
|
||||
- **命名约定**:
|
||||
- 变量和函数使用 camelCase
|
||||
- 类和接口使用 PascalCase
|
||||
- 常量使用 UPPER_SNAKE_CASE
|
||||
- **类型注解**: 尽可能使用类型注解提高代码可读性和类型安全性
|
||||
- **注释**: 对复杂逻辑和公共 API 添加适当的注释
|
||||
|
||||
## Git 提交规范
|
||||
|
||||
我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范来格式化 Git 提交信息。提交信息应遵循以下格式：
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
### 类型 (Type)
|
||||
|
||||
提交类型必须是以下之一：
|
||||
|
||||
- `feat`: 新功能
|
||||
- `fix`: 修复 bug
|
||||
- `docs`: 文档更新
|
||||
- `style`: 代码风格更改（不影响代码功能）
|
||||
- `refactor`: 代码重构（既不是新功能，也不是修复 bug）
|
||||
- `perf`: 性能优化
|
||||
- `test`: 添加或修改测试
|
||||
- `chore`: 构建过程或辅助工具的变动
|
||||
- `ci`: CI 配置文件和脚本的更改
|
||||
- `revert`: 回滚之前的提交
|
||||
|
||||
### 范围 (Scope)
|
||||
|
||||
范围是可选的，用于指定更改的范围（例如组件或文件名）。
|
||||
|
||||
### 描述 (Description)
|
||||
|
||||
描述是对更改的简短摘要：
|
||||
|
||||
- 使用现在时态（"change"，而不是"changed"或"changes"）
|
||||
- 不要首字母大写
|
||||
- 不要以句号结尾
|
||||
|
||||
### 示例
|
||||
|
||||
```
|
||||
feat(editor): 添加拖拽调整组件大小功能
|
||||
|
||||
添加了一个新的拖拽句柄，允许用户直接调整组件的大小。
|
||||
同时优化了调整过程中的性能。
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
```
|
||||
fix: 修复用户认证失败问题
|
||||
|
||||
修复了当用户凭证包含特殊字符时认证失败的问题。
|
||||
|
||||
Fixes #456
|
||||
```
|
||||
|
||||
## CSS/SCSS 规范
|
||||
|
||||
UPage 使用 SCSS 和 CSS Modules 来组织样式代码。
|
||||
|
||||
### 命名约定
|
||||
|
||||
- 使用 kebab-case 命名 CSS 类和 ID
|
||||
- 使用有意义的名称，避免过于简短或抽象的名称
|
||||
- 使用 BEM（Block Element Modifier）命名方法论
|
||||
|
||||
### 组织结构
|
||||
|
||||
- 将全局样式放在 `app/styles` 目录下
|
||||
- 将组件特定样式放在组件同级目录下的 `.scss` 或 `.module.scss` 文件中
|
||||
|
||||
## 可访问性标准
|
||||
|
||||
UPage 致力于创建可访问的 Web 应用程序。所有贡献的代码应遵循 [WCAG 2.1 AA](https://www.w3.org/WAI/WCAG21/quickref/) 标准。
|
||||
|
||||
- 确保适当的颜色对比度
|
||||
- 提供替代文本和 ARIA 标签
|
||||
- 确保键盘导航功能
|
||||
- 支持屏幕阅读器
|
||||
|
||||
## 测试规范
|
||||
|
||||
所有新功能和 bug 修复应包含适当的测试：
|
||||
|
||||
- **单元测试**: 测试单个函数和组件
|
||||
- **集成测试**: 测试多个组件或功能的交互
|
||||
- **端到端测试**: 测试完整的用户流程
|
||||
|
||||
测试应该：
|
||||
|
||||
- 覆盖正常和边缘情况
|
||||
- 清晰描述测试的目的
|
||||
- 保持独立性，不依赖于其他测试的状态
|
||||
|
||||
## 性能考虑
|
||||
|
||||
贡献的代码应考虑性能影响：
|
||||
|
||||
- 避免不必要的重新渲染
|
||||
- 优化大型列表和表格
|
||||
- 懒加载大型资源
|
||||
- 减少网络请求
|
||||
- 优化打包大小
|
||||
|
||||
## 安全最佳实践
|
||||
|
||||
所有代码应遵循安全最佳实践：
|
||||
|
||||
- 防止 XSS 攻击
|
||||
- 避免 SQL 注入
|
||||
- 正确处理用户输入
|
||||
- 保护敏感数据
|
||||
- 实施适当的访问控制
|
||||
161
docs/content/contributing/development-setup.md
Normal file
161
docs/content/contributing/development-setup.md
Normal file
@@ -0,0 +1,161 @@
|
||||
---
|
||||
id: development-setup
|
||||
title: 开发环境设置
|
||||
---
|
||||
|
||||
# 开发环境设置
|
||||
|
||||
本指南将帮助您设置 UPage 的本地开发环境，以便您可以开始贡献代码。
|
||||
|
||||
## 前置条件
|
||||
|
||||
开始开发 UPage 前，请确保您的系统满足以下要求：
|
||||
|
||||
- **Node.js**: 18.18.0 或更高版本
|
||||
- **pnpm**: 9.4.0 或更高版本
|
||||
- **Git**: 最新版本
|
||||
|
||||
### 安装 Node.js
|
||||
|
||||
您可以从 [Node.js 官网](https://nodejs.org/) 下载并安装 Node.js，或使用版本管理工具如 [nvm](https://github.com/nvm-sh/nvm)：
|
||||
|
||||
```bash
|
||||
# 使用 nvm 安装 Node.js
|
||||
nvm install 18.18.0
|
||||
nvm use 18.18.0
|
||||
```
|
||||
|
||||
### 安装 pnpm
|
||||
|
||||
安装 pnpm 的最简单方法是通过 npm：
|
||||
|
||||
```bash
|
||||
npm install -g pnpm@9.4.0
|
||||
```
|
||||
|
||||
或者按照 [pnpm 官方文档](https://pnpm.io/installation) 的说明进行安装。
|
||||
|
||||
## 克隆仓库
|
||||
|
||||
首先，[fork UPage 仓库](https://github.com/halo-dev/upage/fork)到您的 GitHub 账户，然后将其克隆到本地：
|
||||
|
||||
```bash
|
||||
# 克隆您 fork 的仓库
|
||||
git clone https://github.com/YOUR-USERNAME/upage.git
|
||||
|
||||
# 进入项目目录
|
||||
cd upage
|
||||
|
||||
# 添加上游仓库
|
||||
git remote add upstream https://github.com/halo-dev/upage.git
|
||||
```
|
||||
|
||||
## 安装依赖
|
||||
|
||||
使用 pnpm 安装项目依赖：
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## 生成 Prisma 客户端
|
||||
|
||||
UPage 使用 Prisma 作为数据库 ORM，因此需要生成 Prisma 客户端。
|
||||
|
||||
```bash
|
||||
pnpm setup
|
||||
```
|
||||
|
||||
## 配置环境变量
|
||||
|
||||
拷贝 `.env.example` 文件，创建 `.env` 文件：
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
按照[配置参考](../configuration)的说明修改 `.env` 文件进行配置。
|
||||
|
||||
## 启用 Logto 认证（可选）
|
||||
|
||||
UPage 默认仅支持单一用户匿名访问，如果您想要开发用户认证功能，可以按照[Logto 认证集成](../deployment/logto)的说明配置 Logto 认证。
|
||||
|
||||
## 启动开发服务器
|
||||
|
||||
启动开发服务器，这将允许您在本地预览和测试您的更改：
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
此命令会启动开发服务器，您可以通过 `http://localhost:5173` 访问。
|
||||
|
||||
## 构建项目
|
||||
|
||||
要构建生产版本的项目，运行：
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
|
||||
构建完成后，您可以通过以下命令预览生产版本：
|
||||
|
||||
```bash
|
||||
pnpm preview
|
||||
```
|
||||
|
||||
预生产版本项目运行在 `http://localhost:3000`。
|
||||
|
||||
## 运行测试
|
||||
|
||||
运行项目的测试套件：
|
||||
|
||||
```bash
|
||||
pnpm test
|
||||
```
|
||||
|
||||
## 文档开发
|
||||
|
||||
如果您想要修改或预览文档，可以使用以下命令：
|
||||
|
||||
```bash
|
||||
# 启动文档开发服务器
|
||||
pnpm docs:start
|
||||
|
||||
# 构建文档
|
||||
pnpm docs:build
|
||||
```
|
||||
|
||||
文档开发服务器默认在 `http://localhost:3000` 运行。
|
||||
|
||||
## 常见问题解决
|
||||
|
||||
### 依赖安装失败
|
||||
|
||||
如果您在安装依赖时遇到问题，可以尝试以下解决方案：
|
||||
|
||||
```bash
|
||||
# 清除 pnpm 缓存
|
||||
pnpm store prune
|
||||
|
||||
# 重新安装依赖
|
||||
pnpm install --force
|
||||
```
|
||||
|
||||
### 开发服务器启动失败
|
||||
|
||||
如果开发服务器无法启动，请检查：
|
||||
|
||||
1. 端口 5173 是否被其他应用占用
|
||||
2. Node.js 版本是否符合要求
|
||||
3. 是否所有依赖都已正确安装
|
||||
|
||||
您可以尝试使用不同的端口启动：
|
||||
|
||||
```bash
|
||||
pnpm dev --port 5174
|
||||
```
|
||||
|
||||
### 其他问题
|
||||
|
||||
如果您遇到其他问题，请查看项目的 [常见问题](../faq.md) 或在 [GitHub Issues](https://github.com/halo-dev/upage/issues) 中搜索相关问题。如果没有找到解决方案，请创建新的 issue。
|
||||
28
docs/content/contributing/index.md
Normal file
28
docs/content/contributing/index.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
id: contributing
|
||||
title: 贡献指南
|
||||
slug: /contributing
|
||||
---
|
||||
|
||||
# 贡献指南
|
||||
|
||||
感谢您对 UPage 项目的关注！我们非常欢迎各种形式的贡献，无论是功能开发、bug 修复、文档改进还是使用反馈。本指南将帮助您了解如何参与 UPage 的开发和贡献。
|
||||
|
||||
## 目录
|
||||
|
||||
- [行为准则](./code-of-conduct.md) - 参与 UPage 项目的行为准则
|
||||
- [贡献方式](./ways-to-contribute.md) - 如何为 UPage 项目做出贡献
|
||||
- [开发环境设置](./development-setup.md) - 如何设置本地开发环境
|
||||
- [代码规范](./code-standards.md) - 代码风格和提交规范
|
||||
- [工作流程](./workflow.md) - 分支策略、PR流程和版本发布
|
||||
|
||||
## 社区
|
||||
|
||||
加入 UPage 社区，与其他贡献者交流：
|
||||
|
||||
- [GitHub Discussions](https://github.com/halo-dev/upage/discussions)
|
||||
- [GitHub Issues](https://github.com/halo-dev/upage/issues)
|
||||
|
||||
## 许可证
|
||||
|
||||
UPage 采用 [基于 GPLv3 的补充协议许可证](https://github.com/halo-dev/upage/blob/main/LICENSE.txt)。通过贡献代码，您同意您的贡献将在相同的许可证下发布。
|
||||
91
docs/content/contributing/ways-to-contribute.md
Normal file
91
docs/content/contributing/ways-to-contribute.md
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
id: ways-to-contribute
|
||||
title: 贡献方式
|
||||
---
|
||||
|
||||
# 贡献方式
|
||||
|
||||
您可以通过多种方式为 UPage 做出贡献，无论您是开发者、设计师、文档撰写者还是用户，都能找到适合您的贡献方式。
|
||||
|
||||
## 报告问题
|
||||
|
||||
如果您发现了 bug 或有功能建议，请在 [GitHub Issues](https://github.com/halo-dev/upage/issues) 中提出。提交问题时，请尽可能提供以下信息：
|
||||
|
||||
- 清晰的问题描述
|
||||
- 复现步骤
|
||||
- 预期行为与实际行为
|
||||
- 截图（如适用）
|
||||
- 环境信息（浏览器、操作系统、UPage 版本等）
|
||||
|
||||
## 提交代码
|
||||
|
||||
如果您想直接贡献代码，请遵循以下步骤：
|
||||
|
||||
1. [Fork](https://github.com/halo-dev/upage/fork) 项目仓库
|
||||
2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`)
|
||||
3. 提交您的更改 (`git commit -m 'Add some amazing feature'`)
|
||||
4. 推送到分支 (`git push origin feature/amazing-feature`)
|
||||
5. 创建 Pull Request
|
||||
|
||||
### 代码贡献指南
|
||||
|
||||
- 确保您的代码符合项目的[代码规范](./code-standards.md)
|
||||
- 为新功能编写测试
|
||||
- 更新相关文档
|
||||
- 确保所有测试通过
|
||||
- 遵循[工作流程](./workflow.md)中的分支策略和 PR 流程
|
||||
|
||||
## 改进文档
|
||||
|
||||
文档对于任何项目都至关重要。您可以通过以下方式改进 UPage 的文档：
|
||||
|
||||
- 修复文档中的错误或不准确之处
|
||||
- 添加缺失的信息或示例
|
||||
- 改进文档的结构和可读性
|
||||
- 翻译文档到其他语言
|
||||
|
||||
### 文档贡献步骤
|
||||
|
||||
1. 在 `docs/content` 目录中找到相关的 Markdown 文件
|
||||
2. 进行必要的更改
|
||||
3. 在本地预览更改：`pnpm docs:start`
|
||||
4. 提交 Pull Request
|
||||
|
||||
## 设计贡献
|
||||
|
||||
如果您是设计师，您可以通过以下方式贡献：
|
||||
|
||||
- 改进用户界面设计
|
||||
- 创建图标和插图
|
||||
- 设计宣传材料
|
||||
- 提供用户体验建议
|
||||
|
||||
## 测试和反馈
|
||||
|
||||
即使您不是开发者，您也可以通过以下方式做出重要贡献：
|
||||
|
||||
- 测试新功能和版本
|
||||
- 提供详细的反馈
|
||||
- 报告使用过程中遇到的问题
|
||||
- 提出改进建议
|
||||
|
||||
## 分享和推广
|
||||
|
||||
您也可以通过以下方式支持 UPage：
|
||||
|
||||
- 在社交媒体上分享项目
|
||||
- 撰写关于 UPage 的博客文章或教程
|
||||
- 在相关论坛和社区中推荐 UPage
|
||||
- 为项目加星标（Star）
|
||||
|
||||
## 社区支持
|
||||
|
||||
帮助其他用户解决问题也是一种重要的贡献方式：
|
||||
|
||||
- 回答 [GitHub Discussions](https://github.com/halo-dev/upage/discussions) 中的问题
|
||||
- 帮助新用户入门
|
||||
- 分享您的使用经验和最佳实践
|
||||
|
||||
## 感谢您的贡献
|
||||
|
||||
无论您以何种方式支持和参与 UPage 项目，我们都由衷地感谢您的每一份贡献。正是因为有诸多像您这样的社区成员的支持和参与，UPage 才能不断成长和进步。每一个问题报告、每一行代码、每一份文档改进以及每一次分享都是宝贵的。
|
||||
143
docs/content/contributing/workflow.md
Normal file
143
docs/content/contributing/workflow.md
Normal file
@@ -0,0 +1,143 @@
|
||||
---
|
||||
id: workflow
|
||||
title: 工作流程
|
||||
---
|
||||
|
||||
# 工作流程
|
||||
|
||||
本文档描述了 UPage 项目的开发工作流程，包括分支策略、Pull Request 流程和版本发布流程。
|
||||
|
||||
## 分支策略
|
||||
|
||||
UPage 项目使用以下分支策略：
|
||||
|
||||
### 主要分支
|
||||
|
||||
- **`main`**: 主分支，包含最新的开发代码，用于集成功能和修复，同时也对应最新的发布版本
|
||||
|
||||
### 功能分支
|
||||
|
||||
开发新功能时，应从 `main` 分支创建功能分支：
|
||||
|
||||
- **`feature/*`**: 功能分支，用于开发新功能
|
||||
- 例如：`feature/drag-and-drop`、`feature/user-authentication`
|
||||
|
||||
### 修复分支
|
||||
|
||||
修复 bug 时，应从 `main` 分支创建修复分支：
|
||||
|
||||
- **`fix/*`**: 修复分支，用于修复 bug
|
||||
- 例如：`fix/login-error`、`fix/memory-leak`
|
||||
|
||||
### 发布分支
|
||||
|
||||
准备新版本发布时，从 `main` 分支创建发布分支：
|
||||
|
||||
- **`release/*`**: 发布分支，用于准备新版本发布
|
||||
- 例如：`release/v1.0.0`、`release/v1.1.0`
|
||||
|
||||
### 热修复分支
|
||||
|
||||
对已发布版本的紧急修复，从 `main` 分支创建热修复分支：
|
||||
|
||||
- **`hotfix/*`**: 热修复分支，用于对已发布版本的紧急修复
|
||||
- 例如：`hotfix/v1.0.1`、`hotfix/v1.1.2`
|
||||
|
||||
## 工作流程图
|
||||
|
||||
```
|
||||
main ─────┬───────────────┬─────────────────────────────────
|
||||
│ │ ↑ ↑
|
||||
↓ ↓ │ │
|
||||
feature feature/A feature/B │ │
|
||||
│ │
|
||||
fix fix/bug-1 fix/bug-2
|
||||
│ │ │
|
||||
│ │ │
|
||||
release └─────────────────────────────────┴───────────┘
|
||||
release/v1.0.0
|
||||
```
|
||||
|
||||
## Pull Request 流程
|
||||
|
||||
### 准备 Pull Request
|
||||
|
||||
1. 确保您的代码符合项目的[代码规范](./code-standards.md)
|
||||
2. 更新相关文档（如适用）
|
||||
3. 添加或更新测试（如适用）
|
||||
4. 确保所有测试通过
|
||||
5. 将您的分支与目标分支（通常是 `main`）同步
|
||||
|
||||
### 创建 Pull Request
|
||||
|
||||
1. 在 GitHub 上创建一个新的 Pull Request
|
||||
2. 选择正确的目标分支（通常是 `main`）
|
||||
3. 填写 Pull Request 模板，提供以下信息：
|
||||
- 清晰的标题，简要描述更改
|
||||
- 详细的描述，解释更改的目的和实现方式
|
||||
- 相关的 issue 链接（如适用）
|
||||
- 截图或视频（如适用）
|
||||
- 任何需要审核者特别注意的事项
|
||||
|
||||
### Pull Request 审核
|
||||
|
||||
1. 至少需要一个项目维护者的批准才能合并 PR
|
||||
2. 审核者可能会要求进行更改
|
||||
3. 根据反馈进行必要的更改
|
||||
4. 确保 CI 检查通过
|
||||
|
||||
### 合并 Pull Request
|
||||
|
||||
1. 一旦 PR 获得批准并且所有检查通过，它将被合并
|
||||
2. 通常使用 "Squash and merge" 策略，将所有提交合并为一个
|
||||
3. 合并后，相关的分支可以被删除
|
||||
|
||||
## 版本发布流程
|
||||
|
||||
UPage 遵循 [语义化版本控制](https://semver.org/) 规范。版本号格式为 `X.Y.Z`：
|
||||
|
||||
- **X**: 主版本号，当进行不兼容的 API 更改时递增
|
||||
- **Y**: 次版本号，当添加向后兼容的功能时递增
|
||||
- **Z**: 修订号，当进行向后兼容的 bug 修复时递增
|
||||
|
||||
### 发布准备
|
||||
|
||||
1. 从 `main` 分支创建发布分支，例如 `release/v1.0.0`
|
||||
2. 在发布分支上进行最终测试和修复
|
||||
3. 更新版本号和更新日志
|
||||
4. 创建 Pull Request 将发布分支合并回 `main`
|
||||
|
||||
### 发布步骤
|
||||
|
||||
1. 合并发布分支到 `main`
|
||||
2. 在 `main` 分支上创建版本标签，例如 `v1.0.0`
|
||||
3. 发布 GitHub Release，包含详细的更新日志
|
||||
|
||||
### 热修复发布
|
||||
|
||||
1. 从 `main` 分支创建热修复分支，例如 `hotfix/v1.0.1`
|
||||
2. 实现必要的修复
|
||||
3. 更新版本号和更新日志
|
||||
4. 创建 Pull Request 将热修复分支合并到 `main`
|
||||
5. 必要时创建 cherry-pick PR 将热修复分支合并到对应的发布分支
|
||||
|
||||
## 持续集成和部署
|
||||
|
||||
UPage 使用 GitHub Actions 进行持续集成和部署：
|
||||
|
||||
### CI 工作流程
|
||||
|
||||
- 每个 PR 会触发构建和测试
|
||||
- 代码质量检查（linting、类型检查）
|
||||
- 单元测试和集成测试
|
||||
- 构建检查
|
||||
|
||||
### CD 工作流程
|
||||
|
||||
- 合并到 `main` 分支会触发开发构建和部署
|
||||
- 自动生成和发布 Docker 镜像
|
||||
- 更新文档网站
|
||||
|
||||
## 问题跟踪
|
||||
|
||||
UPage 使用 GitHub [Issues](https://github.com/halo-dev/upage/issues) 进行问题跟踪，使用标签对问题进行分类（bug、feature、documentation 等）
|
||||
@@ -34,6 +34,15 @@ Logto 支持两种接入方式，您可以根据自己的需求选择合适的
|
||||
|
||||
UPage 提供了一个简化的 Logto 部署配置。在 UPage 项目目录下，您可以找到 `logto/docker-compose.yaml` 文件以及 `.env` 文件。
|
||||
|
||||
如果是开发环境，执行以下命令：
|
||||
|
||||
```bash
|
||||
cd ./logto
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
如果是生产环境，执行以下命令：
|
||||
|
||||
```bash
|
||||
curl -L https://raw.githubusercontent.com/halo-dev/upage/refs/heads/main/logto/docker-compose.yaml -o ~/upage/logto/docker-compose.yaml
|
||||
curl -L https://raw.githubusercontent.com/halo-dev/upage/refs/heads/main/logto/.env -o ~/upage/logto/.env
|
||||
|
||||
@@ -11,7 +11,7 @@ title: 常见问题
|
||||
|
||||
### UPage 是什么？
|
||||
|
||||
UPage 是一款基于人工智能的可视化网页构建平台，支持多种 AI 提供商集成，基于自然语言快速实现定制化网页。它允许用户通过简单的文字描述生成完整的网页，并提供可视化编辑工具进行进一步定制。
|
||||
UPage 是一款基于大模型的可视化网页构建平台，支持多种 AI 提供商集成，基于自然语言快速实现定制化网页。它允许用户通过简单的文字描述生成完整的网页，并提供可视化编辑工具进行进一步定制。
|
||||
|
||||
### UPage 适合哪些用户？
|
||||
|
||||
@@ -26,7 +26,7 @@ UPage 适合各类需要快速创建网页的用户，包括但不限于：
|
||||
|
||||
### UPage 是开源的吗？
|
||||
|
||||
是的，UPage 是一个开源项目，采用 MIT 许可证。您可以在 [GitHub](https://github.com/halo-dev/upage) 上查看源代码，也可以参与项目开发和改进。
|
||||
是的，UPage 是一个开源项目，采用 [基于 GPLv3 的补充协议许可证](https://github.com/halo-dev/upage/blob/main/LICENSE.txt)。您可以在 [GitHub](https://github.com/halo-dev/upage) 上查看源代码，也可以参与项目开发和改进。
|
||||
|
||||
## 安装和部署
|
||||
|
||||
@@ -40,16 +40,17 @@ docker run -d \
|
||||
--restart unless-stopped \
|
||||
-p 3000:3000 \
|
||||
-e LLM_DEFAULT_PROVIDER=OpenAILike \
|
||||
-e OPENAI_LIKE_API_BASE_URL=your-openai-like-api-base-url \
|
||||
-e OPENAI_LIKE_API_KEY=your-openai-like-api-key \
|
||||
-e LLM_DEFAULT_MODEL=your-default-model \
|
||||
-e LLM_MINOR_MODEL=your-minor-model \
|
||||
-v ./data:/app/data \
|
||||
-v ./logs:/app/logs \
|
||||
-v ./storage:/app/storage \
|
||||
ghcr.io/halo-dev/upage
|
||||
halo-dev/upage:latest
|
||||
```
|
||||
|
||||
详细的安装说明请参考[快速开始](quick-start)文档。
|
||||
详细的安装说明请参考[快速开始](./quick-start)文档。
|
||||
|
||||
### UPage 的系统要求是什么？
|
||||
|
||||
@@ -58,7 +59,7 @@ UPage 的最低系统要求：
|
||||
- Docker 20.10.0 或更高版本（如果使用 Docker 部署）
|
||||
- Node.js 18.18.0 或更高版本（如果源码部署）
|
||||
- 至少 2GB 可用内存
|
||||
- 至少 1GB 可用磁盘空间
|
||||
- 至少 2GB 可用磁盘空间
|
||||
- 互联网连接（用于访问 AI API）
|
||||
|
||||
### 如何更新 UPage？
|
||||
@@ -67,7 +68,7 @@ UPage 的最低系统要求：
|
||||
|
||||
```bash
|
||||
# 拉取最新镜像
|
||||
docker pull ghcr.io/halo-dev/upage:latest
|
||||
docker pull halo-dev/upage:latest
|
||||
|
||||
# 停止并删除旧容器
|
||||
docker stop upage
|
||||
@@ -79,7 +80,7 @@ docker run -d \
|
||||
--restart unless-stopped \
|
||||
-p 3000:3000 \
|
||||
... # 其他环境变量和挂载
|
||||
ghcr.io/halo-dev/upage:latest
|
||||
halo-dev/upage:latest
|
||||
```
|
||||
|
||||
如果使用 Docker Compose，则可以执行：
|
||||
@@ -96,12 +97,15 @@ docker-compose up -d
|
||||
|
||||
UPage 支持多种 AI 提供商，包括：
|
||||
|
||||
- OpenAI（GPT-3.5、GPT-4 等）
|
||||
- DeepSeek（DeepSeek-Chat、DeepSeek-Reasoner）
|
||||
- OpenAI（GPT-4o、GPT-5 等）
|
||||
- Anthropic Claude
|
||||
- Google Gemini
|
||||
- 兼容 OpenAI 接口的服务（如 Azure OpenAI、智谱 AI 等）
|
||||
- Ollama（本地部署的开源模型）
|
||||
|
||||
所有支持的 AI 提供商请参考[配置参考- AI 提供商配置](./configuration#ai-提供商配置)文档。
|
||||
|
||||
### 如何配置 AI 提供商？
|
||||
|
||||
通过环境变量配置 AI 提供商，例如：
|
||||
@@ -120,11 +124,11 @@ UPage 支持多种 AI 提供商，包括：
|
||||
-e LLM_MINOR_MODEL=claude-3-haiku-20240307
|
||||
```
|
||||
|
||||
详细的配置选项请参考[配置参考](configuration)文档。
|
||||
详细的配置选项请参考[配置参考 - AI 提供商配置](./configuration#ai-提供商配置)文档。
|
||||
|
||||
### 使用 AI 生成页面需要多少 token？
|
||||
|
||||
生成一个标准页面通常需要 2,000-10,000 个 token，具体取决于页面的复杂度和内容量。复杂的页面可能需要更多 token。UPage 会优化 prompt，尽量减少 token 消耗。
|
||||
生成一个标准页面通常需要 2,000-10,000 个 token，具体取决于页面的复杂度和内容量。复杂的页面可能需要更多 token。UPage 会尽可能优化 prompt，尽量减少 token 消耗。
|
||||
|
||||
### 如何优化 AI 提示以获得更好的结果？
|
||||
|
||||
@@ -145,35 +149,22 @@ UPage 支持多种 AI 提供商，包括：
|
||||
...
|
||||
```
|
||||
|
||||
你可以使用 UPage 的优化提示功能来优化您的提示。
|
||||
|
||||
## 使用问题
|
||||
|
||||
### 如何创建第一个页面？
|
||||
|
||||
1. 登录 UPage
|
||||
2. 点击侧边栏中的"新建页面"按钮
|
||||
3. 选择"AI 创建"、"从模板创建"或"空白页面"
|
||||
4. 如果选择 AI 创建，输入页面描述并点击"生成"
|
||||
5. 等待 AI 生成页面，然后进行进一步编辑
|
||||
|
||||
### 如何编辑 AI 生成的页面？
|
||||
|
||||
1. 在页面列表中选择要编辑的页面
|
||||
2. 使用可视化编辑器修改页面元素
|
||||
3. 可以拖拽组件、调整布局、编辑文本和图片
|
||||
4. 使用右侧属性面板修改组件属性和样式
|
||||
5. 也可以使用 AI 辅助功能进行局部或整体调整
|
||||
|
||||
### 如何导出页面？
|
||||
|
||||
1. 在页面列表中选择要导出的页面
|
||||
2. 点击操作菜单中的"导出"选项
|
||||
3. 选择导出格式（HTML/CSS/JS、ZIP、JSON 或 PDF）
|
||||
4. 配置导出选项
|
||||
5. 点击"导出"开始下载
|
||||
2. 使用可视化编辑器点击要修改的页面元素
|
||||
3. 对于文本组件，可以直接输入文本进行修改
|
||||
4. 对于图片组件，可以点击上传图片进行替换
|
||||
5. 使用弹出的属性面板修改组件属性和样式
|
||||
6. 也可以使用 AI 辅助功能进行局部或整体调整
|
||||
|
||||
### UPage 支持响应式设计吗？
|
||||
|
||||
是的，UPage 生成的页面默认支持响应式设计，可以自动适应不同屏幕尺寸。您可以在编辑器中预览页面在不同设备上的显示效果，并进行针对性调整。
|
||||
是的，UPage 生成的页面默认支持响应式设计，可以自动适应不同屏幕尺寸。您可以在编辑器中预览页面在不同设备上的显示效果，并进行针对性调整。如果生成的页面不符合您的预期，您可以尝试使用 AI 辅助调整。
|
||||
|
||||
## 数据和安全
|
||||
|
||||
@@ -197,9 +188,9 @@ tar -czf upage-storage-backup-$(date +%Y%m%d).tar.gz ./storage
|
||||
|
||||
UPage 本身不会收集或传输用户数据，除非明确配置。当使用 AI 功能时，页面内容会发送到配置的 AI 提供商进行处理。请确保您使用的 AI 提供商符合您的隐私要求。
|
||||
|
||||
### 如何配置 UPage 的访问控制？
|
||||
### 如何配置 UPage 的多用户？
|
||||
|
||||
UPage 支持通过 Logto 进行用户认证和访问控制。配置 Logto 后，您可以创建用户账户、分配角色和权限，实现细粒度的访问控制。详细配置请参考[Logto 认证集成](deployment/logto)文档。
|
||||
UPage 支持通过 Logto 进行用户认证和访问控制。详细配置请参考[Logto 认证集成](deployment/logto)文档。
|
||||
|
||||
## 故障排除
|
||||
|
||||
@@ -211,10 +202,11 @@ UPage 支持通过 Logto 进行用户认证和访问控制。配置 Logto 后，
|
||||
2. **提示过于复杂**：尝试简化页面描述，分步骤生成
|
||||
3. **token 限制**：检查是否达到 AI 提供商的 token 限制
|
||||
4. **模型不支持**：尝试使用更强大的模型或不同的 AI 提供商
|
||||
5. **生成内容超过限制**：UPage 默认限制单次回答不超过 3 次 Token 上限，您可以尝试分步骤生成
|
||||
|
||||
### 如何查看系统日志？
|
||||
|
||||
可以通过以下方式查看系统日志：
|
||||
默认情况下，UPage 会将日志保存在挂载的 `logs` 目录中，可以通过以下方式查看系统日志：
|
||||
|
||||
```bash
|
||||
# 查看容器日志
|
||||
@@ -254,33 +246,15 @@ cat logs/combined-*.log
|
||||
|
||||
## 高级问题
|
||||
|
||||
### 如何自定义 UPage 的主题？
|
||||
|
||||
目前 UPage 不支持完全自定义主题，但您可以通过以下方式调整外观：
|
||||
|
||||
1. 在页面编辑器中使用自定义 CSS
|
||||
2. 使用 AI 生成符合特定设计风格的页面
|
||||
3. 在导出的代码中进行进一步自定义
|
||||
|
||||
### UPage 支持插件系统吗？
|
||||
|
||||
目前 UPage 不提供正式的插件系统，但作为开源项目，您可以通过 fork 代码库并进行修改来扩展功能。
|
||||
UPage 不提供正式的插件系统，但作为开源项目，您可以通过 fork 代码库并进行修改来扩展功能。
|
||||
|
||||
### 如何与现有系统集成？
|
||||
|
||||
UPage 提供多种集成方式：
|
||||
|
||||
1. **API 集成**：使用 UPage API 与其他系统交互
|
||||
2. **导出集成**：导出页面代码并集成到现有系统
|
||||
2. **导出集成**：下载页面源代码（HTML/CSS/JS）并集成到现有系统
|
||||
3. **部署集成**：使用 Vercel 或 Netlify 集成直接部署页面
|
||||
4. **认证集成**：通过 Logto 与现有认证系统集成
|
||||
|
||||
### UPage 与其他页面构建器的区别是什么？
|
||||
|
||||
UPage 的主要区别在于：
|
||||
|
||||
1. **AI 驱动**：基于自然语言描述生成页面
|
||||
2. **开源**：完全开源，可自由定制和扩展
|
||||
3. **多 AI 提供商支持**：支持多种 AI 模型和提供商
|
||||
4. **本地部署**：可在本地或私有云部署，保护数据安全
|
||||
5. **轻量级**：资源占用较低，易于部署和维护
|
||||
|
||||
@@ -21,6 +21,10 @@ UPage 是一个开源的网页构建工具，它利用大语言模型，让用
|
||||
- **响应式设计**：自动适应不同屏幕尺寸
|
||||
- **部署集成**：支持一键部署到常见托管平台
|
||||
|
||||
:::note
|
||||
特别感谢 [bolt.diy](https://github.com/stackblitz-labs/bolt.diy) 项目，UPage 的实现基于该项目的代码结构。
|
||||
:::
|
||||
|
||||
## 快速开始
|
||||
|
||||
请查看[快速开始](quick-start.md)指南，了解如何安装和使用 UPage。
|
||||
@@ -31,4 +35,4 @@ UPage 是一个开源项目，我们欢迎任何形式的贡献。请查看[贡
|
||||
|
||||
## 许可证
|
||||
|
||||
UPage 采用 [基于 GPLv3 的补充协议许可证](https://github.com/halo-dev/upage/blob/main/LICENSE)。
|
||||
UPage 采用 [基于 GPLv3 的补充协议许可证](https://github.com/halo-dev/upage/blob/main/LICENSE.txt)。
|
||||
|
||||
@@ -68,7 +68,7 @@ const config = {
|
||||
type: 'docSidebar',
|
||||
sidebarId: 'tutorialSidebar',
|
||||
position: 'left',
|
||||
label: '文档',
|
||||
label: '使用文档',
|
||||
},
|
||||
{
|
||||
href: 'https://github.com/halo-dev/upage',
|
||||
@@ -116,7 +116,7 @@ const config = {
|
||||
],
|
||||
},
|
||||
],
|
||||
copyright: `Copyright © ${new Date().getFullYear()} Halo 社区`,
|
||||
copyright: `Copyright © ${new Date().getFullYear()} 凌霞软件. Built with Docusaurus.`,
|
||||
},
|
||||
prism: {
|
||||
theme: require('prism-react-renderer').themes.github,
|
||||
|
||||
@@ -58,20 +58,25 @@ const sidebars = {
|
||||
],
|
||||
},
|
||||
{
|
||||
type: 'doc',
|
||||
id: 'contributing',
|
||||
type: 'category',
|
||||
label: '贡献指南',
|
||||
link: {
|
||||
type: 'doc',
|
||||
id: 'contributing/contributing',
|
||||
},
|
||||
items: [
|
||||
'contributing/code-of-conduct',
|
||||
'contributing/ways-to-contribute',
|
||||
'contributing/development-setup',
|
||||
'contributing/code-standards',
|
||||
'contributing/workflow',
|
||||
],
|
||||
},
|
||||
{
|
||||
type: 'doc',
|
||||
id: 'faq',
|
||||
label: '常见问题',
|
||||
},
|
||||
{
|
||||
type: 'doc',
|
||||
id: 'changelog',
|
||||
label: '更新日志',
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
|
||||
Reference in New Issue
Block a user