# PromptForge 安装指南

<div align="center">

![PromptForge](https://img.shields.io/badge/PromptForge-AI%20Prompt%20Engineering-blue?style=for-the-badge&logo=openai)

**从零开始安装和配置 PromptForge 平台**

[![Node.js](https://img.shields.io/badge/Node.js-18+-green?style=flat-square&logo=node.js)](https://nodejs.org/)
[![MySQL](https://img.shields.io/badge/MySQL-8.0+-blue?style=flat-square&logo=mysql)](https://www.mysql.com/)
[![Next.js](https://img.shields.io/badge/Next.js-14-black?style=flat-square&logo=next.js)](https://nextjs.org/)

</div>

## 📋 目录

- [系统要求](#系统要求)
- [快速安装](#快速安装)
- [详细安装步骤](#详细安装步骤)
- [环境配置](#环境配置)
- [数据库设置](#数据库设置)
- [API 密钥配置](#api-密钥配置)
- [验证安装](#验证安装)
- [生产环境部署](#生产环境部署)
- [常见问题](#常见问题)
- [视频教程](#视频教程)
- [获取帮助](#获取帮助)

## 🎯 系统要求

### 最低要求
- **操作系统**: Windows 10+, macOS 10.15+, Ubuntu 18.04+
- **Node.js**: v18.0.0 或更高版本
- **MySQL**: v8.0 或更高版本
- **内存**: 4GB RAM
- **存储**: 2GB 可用空间
- **网络**: 稳定的互联网连接

### 推荐配置
- **操作系统**: Windows 11, macOS 12+, Ubuntu 20.04+
- **Node.js**: v20.0.0 或更高版本
- **MySQL**: v8.0.33 或更高版本
- **内存**: 8GB RAM
- **存储**: 5GB 可用空间
- **网络**: 高速互联网连接

## ⚡ 快速安装

如果您已经安装了 Node.js 和 MySQL，可以直接运行以下命令：

```bash
# 1. 克隆项目
git clone https://github.com/your-username/promptforge.git
cd promptforge

# 2. 安装依赖
npm install

# 3. 配置环境变量
cp .env.example .env.local
# 编辑 .env.local 文件，填入您的配置

# 4. 设置数据库
node create-tables-final.js
node create-template-data.js

# 5. 启动应用
npm run dev
```

访问 [http://localhost:3000](http://localhost:3000) 开始使用！

## 🔧 详细安装步骤

### 第一步：环境准备

#### 1.1 安装 Node.js

**Windows 用户：**
1. 访问 [Node.js 官网](https://nodejs.org/)
2. 下载 LTS 版本（推荐 v20.x）
3. 运行安装程序，选择默认选项
4. 重启命令提示符或 PowerShell
5. 验证安装：
   ```cmd
   node --version
   npm --version
   ```

**macOS 用户：**
```bash
# 使用 Homebrew（推荐）
brew install node

# 或使用官方安装包
# 访问 https://nodejs.org/ 下载安装

# 验证安装
node --version
npm --version
```

**Linux 用户：**
```bash
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# CentOS/RHEL
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# 验证安装
node --version
npm --version
```

#### 1.2 安装 MySQL

**Windows 用户：**
1. 访问 [MySQL 官网](https://dev.mysql.com/downloads/mysql/)
2. 下载 MySQL Community Server
3. 运行安装程序，选择 "Developer Default"
4. 设置 root 密码（请记住这个密码）
5. 完成安装并启动 MySQL 服务

**macOS 用户：**
```bash
# 使用 Homebrew
brew install mysql

# 启动 MySQL 服务
brew services start mysql

# 设置 root 密码
mysql_secure_installation
```

**Linux 用户：**
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install mysql-server

# 启动 MySQL 服务
sudo systemctl start mysql
sudo systemctl enable mysql

# 安全配置
sudo mysql_secure_installation
```

#### 1.3 安装 Git

**Windows 用户：**
1. 访问 [Git 官网](https://git-scm.com/)
2. 下载 Git for Windows
3. 运行安装程序，使用默认选项
4. 配置用户信息：
   ```cmd
   git config --global user.name "Your Name"
   git config --global user.email "your.email@example.com"
   ```

**macOS 用户：**
```bash
# 使用 Homebrew
brew install git

# 或使用官方安装包
# 访问 https://git-scm.com/ 下载安装
```

**Linux 用户：**
```bash
sudo apt update
sudo apt install git
```

### 第二步：项目安装

#### 2.1 克隆项目

```bash
# 克隆项目到本地
git clone https://github.com/your-username/promptforge.git

# 进入项目目录
cd promptforge

# 查看项目结构
ls -la
```

#### 2.2 安装依赖

```bash
# 安装项目依赖
npm install

# 验证安装
npm run type-check

# 如果遇到权限问题，在 Linux/macOS 上使用：
sudo npm install
```

#### 2.3 配置环境变量

创建环境变量文件：

```bash
# Windows
copy .env.example .env.local

# macOS/Linux
cp .env.example .env.local
```

编辑 `.env.local` 文件，配置以下环境变量：

```env
# ==================== 数据库配置 ====================
# 本地 MySQL 数据库
DATABASE_URL=mysql://root:your_password@localhost:3306/promptforge

# 腾讯云数据库（可选，如果使用云数据库）
TENCENT_DATABASE_URL=mysql://root:!Rjb12191@gz-cynosdbmysql-grp-d26pzce5.sql.tencentcdb.com:24936/pronode_db?charset=utf8mb4

# ==================== API 密钥配置 ====================
# OpenAI API（可选，用于测试）
OPENAI_API_KEY=your_openai_api_key_here

# Anthropic API（可选，用于测试）
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# DeepSeek API（可选，用于测试）
DEEPSEEK_API_KEY=sk-fdf7cc1c73504e628ec0119b7e11b8cc

# ==================== 应用配置 ====================
# NextAuth 配置
NEXTAUTH_SECRET=your_secret_key_here_make_it_long_and_random
NEXTAUTH_URL=http://localhost:3000

# ==================== 可选配置 ====================
# 应用端口（默认 3000）
PORT=3000

# 环境模式
NODE_ENV=development
```

### 第三步：数据库设置

#### 3.1 创建数据库

连接到 MySQL：
```bash
mysql -u root -p
```

创建数据库：
```sql
-- 创建主数据库
CREATE DATABASE promptforge CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建腾讯云数据库（如果使用）
CREATE DATABASE pronode_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 查看数据库
SHOW DATABASES;

-- 退出 MySQL
EXIT;
```

#### 3.2 运行数据库初始化脚本

```bash
# 创建数据库表结构
node create-tables-final.js

# 创建测试数据
node create-template-data.js

# 验证数据创建
node verify-data.js

# 如果需要数据迁移
node migrate-prompt-template-data.js
```

### 第四步：验证安装

```bash
# 启动开发服务器
npm run dev
```

在浏览器中访问 [http://localhost:3000](http://localhost:3000)

您应该看到 PromptForge 的欢迎页面。如果一切正常，您将看到：

✅ **成功标志：**
- 页面正常加载
- 没有控制台错误
- 可以访问所有功能模块

## 🔑 API 密钥配置

### 获取 API 密钥

#### OpenAI API
1. 访问 [OpenAI Platform](https://platform.openai.com/)
2. 注册账户并登录
3. 进入 [API Keys](https://platform.openai.com/api-keys) 页面
4. 点击 "Create new secret key"
5. 复制生成的密钥
6. 将密钥添加到 `.env.local` 文件

#### Anthropic API
1. 访问 [Anthropic Console](https://console.anthropic.com/)
2. 注册账户并登录
3. 进入 [API Keys](https://console.anthropic.com/account/keys) 页面
4. 点击 "Create Key"
5. 复制生成的密钥
6. 将密钥添加到 `.env.local` 文件

#### DeepSeek API
1. 访问 [DeepSeek Platform](https://platform.deepseek.com/)
2. 注册账户并登录
3. 进入 API Keys 页面
4. 创建新的 API 密钥
5. 复制密钥到 `.env.local` 文件

### 测试 API 连接

```bash
# 测试 DeepSeek API
node test-deepseek-api.js

# 测试数据库连接
node test-db-connection.js

# 测试用户系统
node test-user-system.js
```

## 🚀 生产环境部署

### 1. 构建生产版本

```bash
# 构建应用
npm run build

# 启动生产服务器
npm start
```

### 2. 使用 PM2 管理进程

```bash
# 安装 PM2
npm install -g pm2

# 创建 PM2 配置文件
cat > ecosystem.config.js << EOF
module.exports = {
  apps: [{
    name: 'promptforge',
    script: 'npm',
    args: 'start',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }]
}
EOF

# 启动应用
pm2 start ecosystem.config.js

# 查看状态
pm2 status

# 查看日志
pm2 logs promptforge

# 设置开机自启
pm2 startup
pm2 save
```

### 3. 配置 Nginx 反向代理

创建 Nginx 配置文件：

```bash
sudo nano /etc/nginx/sites-available/promptforge
```

添加以下内容：

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 安全头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;

    # 静态文件缓存
    location /_next/static/ {
        alias /path/to/promptforge/.next/static/;
        expires 365d;
        access_log off;
    }

    # 主应用
    location / {
        proxy_pass http://localhost:3000;
        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;
        proxy_read_timeout 86400;
    }

    # 健康检查
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }
}
```

启用配置：

```bash
# 创建符号链接
sudo ln -s /etc/nginx/sites-available/promptforge /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重新加载 Nginx
sudo systemctl reload nginx

# 设置防火墙
sudo ufw allow 'Nginx Full'
```

### 4. SSL 证书配置（推荐）

使用 Let's Encrypt 免费 SSL 证书：

```bash
# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 获取 SSL 证书
sudo certbot --nginx -d your-domain.com

# 自动续期
sudo crontab -e
# 添加以下行：
# 0 12 * * * /usr/bin/certbot renew --quiet
```

## 🔧 常见问题

### 1. Node.js 相关问题

**问题**: `npm` 命令未找到
```bash
# 解决方案：重新安装 Node.js
# Windows: 重新下载安装包
# macOS: brew reinstall node
# Linux: 使用 NodeSource 仓库重新安装
```

**问题**: Node.js 版本过低
```bash
# 检查版本
node --version

# 升级 Node.js
# Windows: 下载新版本安装包
# macOS: brew upgrade node
# Linux: 使用 nvm 管理版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20
```

### 2. MySQL 相关问题

**问题**: MySQL 服务未启动
```bash
# 检查服务状态
sudo systemctl status mysql

# 启动服务
sudo systemctl start mysql

# 设置开机自启
sudo systemctl enable mysql
```

**问题**: 无法连接到 MySQL
```bash
# 检查端口
sudo netstat -tlnp | grep 3306

# 检查防火墙
sudo ufw status

# 重置 root 密码
sudo mysql
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'new_password';
FLUSH PRIVILEGES;
EXIT;
```

### 3. 端口占用问题

**问题**: 端口 3000 被占用
```bash
# 查看端口占用
lsof -i :3000

# 杀死占用进程
kill -9 <PID>

# 或使用其他端口
PORT=3001 npm run dev
```

### 4. 权限问题

**问题**: 无法创建或修改文件
```bash
# 检查文件权限
ls -la

# 修改权限
chmod 755 .

# 修改所有者
sudo chown -R $USER:$USER .
```

### 5. 依赖安装失败

**问题**: `npm install` 失败
```bash
# 清除缓存
npm cache clean --force

# 删除 node_modules
rm -rf node_modules package-lock.json

# 重新安装
npm install

# 如果还是失败，尝试使用 yarn
npm install -g yarn
yarn install
```

### 6. 数据库连接问题

**问题**: 数据库连接失败
```bash
# 检查数据库配置
node test-db-connection.js

# 检查环境变量
cat .env.local

# 手动测试连接
mysql -u root -p -h localhost -P 3306
```

### 7. API 测试失败

**问题**: AI 模型 API 调用失败
```bash
# 检查 API 密钥
echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY
echo $DEEPSEEK_API_KEY

# 测试 API 连接
node test-deepseek-api.js

# 检查网络连接
curl -I https://api.openai.com
```

## 📹 视频教程

### 安装教程
- [Windows 安装教程](https://youtube.com/watch?v=example1)
- [macOS 安装教程](https://youtube.com/watch?v=example2)
- [Linux 安装教程](https://youtube.com/watch?v=example3)

### 配置教程
- [数据库配置详解](https://youtube.com/watch?v=example4)
- [API 密钥配置](https://youtube.com/watch?v=example5)
- [生产环境部署](https://youtube.com/watch?v=example6)

## 📞 获取帮助

### 自助解决
1. 查看 [常见问题](#常见问题) 部分
2. 搜索 [GitHub Issues](https://github.com/your-username/promptforge/issues)
3. 查看 [项目 Wiki](https://github.com/your-username/promptforge/wiki)

### 社区支持
- **Discord**: [PromptForge 社区](https://discord.gg/promptforge)
- **Telegram**: [@PromptForgeSupport](https://t.me/PromptForgeSupport)
- **QQ 群**: 123456789

### 技术支持
- **邮箱**: support@promptforge.com
- **工作时间**: 周一至周五 9:00-18:00 (GMT+8)
- **响应时间**: 24 小时内

### 提交问题
如果遇到问题，请按以下格式提交：

```markdown
**问题描述**
详细描述您遇到的问题

**环境信息**
- 操作系统: Windows 10
- Node.js 版本: v20.0.0
- MySQL 版本: v8.0.33
- 错误信息: [粘贴错误信息]

**重现步骤**
1. 第一步
2. 第二步
3. 第三步

**期望结果**
描述您期望看到的结果

**实际结果**
描述实际发生的情况
```

## 🎉 安装完成

恭喜！您已经成功安装了 PromptForge 平台。现在可以：

### 开始使用
1. 访问 [http://localhost:3000](http://localhost:3000)
2. 注册新账户
3. 开始创建您的第一个提示词模板
4. 探索平台的所有功能

### 下一步
- 📖 阅读 [创建第一个模板指南](../TEMPLATE_TUTORIAL.md)
- 🔧 查看 [配置文档](../CONFIGURATION.md)
- 🚀 了解 [部署选项](../DEPLOYMENT_FEATURES.md)
- 🧪 尝试 [测试台功能](../PLAYGROUND_FEATURES.md)

### 功能概览
- ✅ **模板管理** - 创建、编辑、分享模板
- ✅ **AI 测试** - 多模型测试和对比
- ✅ **代码生成** - 一键生成部署代码
- ✅ **用户系统** - 完整的用户管理
- ✅ **设置中心** - 个性化配置

祝您使用愉快！🚀

---

<div align="center">

**PromptForge** - 让 AI 提示词工程更简单

[![GitHub](https://img.shields.io/badge/GitHub-View%20on%20GitHub-black?style=flat-square&logo=github)](https://github.com/your-username/promptforge)
[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
[![Stars](https://img.shields.io/github/stars/your-username/promptforge?style=flat-square)](https://github.com/your-username/promptforge/stargazers)

</div>