python-template/TEMPLATE_QUICK_START.md

模板快速使用指南

三种使用方式

🚀 方式一: 自动化脚本 (最推荐)

# 1. 运行创建脚本
./create-from-template.sh

# 2. 按提示输入项目信息
# 3. 脚本会自动完成所有配置
# 4. 进入新项目目录开始开发

优点:

• ✅ 一键创建，无需手动配置
• ✅ 自动替换所有配置项
• ✅ 自动生成安全的 SECRET_KEY
• ✅ 自动初始化 Git 仓库

---

📋 方式二: 手动复制

# 1. 复制项目
cp -r /path/to/pager /path/to/your-new-project
cd /path/to/your-new-project

# 2. 清理不需要的文件
rm -rf .git backend/__pycache__ backend/*.db backend/uploads/* frontend/node_modules frontend/dist

# 3. 配置后端
cd backend
cp .env.example .env
# 编辑 .env 文件，修改必要配置

# 4. 配置前端
cd frontend
# 编辑 package.json，修改项目名称

# 5. 初始化 Git
git init
git add .
git commit -m "Initial commit"

---

🔗 方式三: Git 模板方式

# 1. 克隆为模板
git clone /path/to/pager your-new-project
cd your-new-project

# 2. 移除原有 Git 历史
rm -rf .git

# 3. 按方式二的步骤 3-5 操作

---

核心配置清单

✅ 必须修改的配置

后端 backend/.env:

# 1. 数据库连接 (必须)
DATABASE_URL=postgresql://user:pass@host:port/dbname

# 2. 密钥 (必须，生产环境)
SECRET_KEY=<生成一个长随机字符串>

# 3. AI API Key (如需 AI 功能)
OPENROUTER_API_KEY=<your-api-key>

前端 frontend/package.json:

{
  "name": "your-project-name-frontend"
}

前端 frontend/index.html:

<title>Your Project Name</title>

---

🔧 可选修改的配置

端口配置:

• 后端: backend/main.py 或 .env 中的 PORT
• 前端: vite.config.js 中的 server.port

API 地址:

• frontend/src/config/index.js

---

快速命令参考

开发环境

# 后端
cd backend
pip install -r requirements.txt  # 安装依赖
python main.py                   # 启动服务

# 前端
cd frontend
npm install                      # 安装依赖
npm run dev                      # 启动开发服务器

# 或使用启动脚本
./start.sh                       # 同时启动前后端
./status.sh                      # 查看运行状态
./stop.sh                        # 停止所有服务

数据库操作

cd backend
python main.py                   # 首次运行自动创建表
python migrate_db.py             # 手动迁移数据库

生产构建

# 前端构建
cd frontend
npm run build                    # 构建到 dist/ 目录
npm run preview                  # 预览生产构建

# 后端生产运行
cd backend
uvicorn main:app --host 0.0.0.0 --port 8888

---

项目结构速览

your-project/
├── backend/                  # FastAPI 后端
│   ├── main.py              # 主应用 (所有 API 在这里)
│   ├── .env                 # 环境变量 (从 .env.example 复制)
│   └── requirements.txt     # Python 依赖
│
├── frontend/                 # Vue 3 前端
│   ├── src/
│   │   ├── views/           # 页面组件
│   │   ├── stores/          # Pinia 状态管理
│   │   ├── router/          # 路由配置
│   │   └── config/          # 配置管理
│   └── package.json         # 前端依赖
│
├── create-from-template.sh  # 模板创建脚本
├── TEMPLATE_GUIDE.md        # 完整使用指南
└── start.sh                 # 开发启动脚本

---

开发工作流

添加新功能

1. 后端 API:

# backend/main.py
@app.get("/api/your-endpoint")
async def your_endpoint(current_user: User = Depends(get_current_user)):
    return {"message": "Hello"}

2. 前端页面:

# 创建组件
touch frontend/src/views/YourPage.vue

# 注册路由 (frontend/src/router/index.js)
{
  path: '/your-page',
  component: () => import('../views/YourPage.vue')
}

3. 状态管理:

// frontend/src/stores/yourStore.js
import { defineStore } from 'pinia'

export const useYourStore = defineStore('your-store', () => {
  // 定义状态和方法
})

---

常见问题速查

问题	解决方法
端口被占用	修改 .env 中的 PORT 或 vite.config.js
CORS 错误	检查 backend/main.py 的 CORS 配置
数据库连接失败	检查 DATABASE_URL 格式和数据库服务状态
前端请求失败	检查 frontend/src/config/index.js 的 API_BASE_URL
JWT 认证失败	确保 SECRET_KEY 正确且前后端一致

---

安全检查清单

• 修改了 SECRET_KEY (生产环境必须)
• 不提交 .env 文件到 Git
• 生产环境设置 DEBUG=false
• 限制 CORS 允许的域名
• 使用 HTTPS (生产环境)
• 定期更新依赖包
• 保护 API keys 安全

---

生成安全密钥

# 方法 1: OpenSSL
openssl rand -base64 32

# 方法 2: Python
python -c "import secrets; print(secrets.token_urlsafe(32))"

# 方法 3: Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

---

部署选项

Docker

docker-compose up -d

PM2

pm2 start backend/main.py --name api
pm2 serve frontend/dist 3000 --name frontend

云服务器

• 阿里云 ECS
• 腾讯云 CVM
• AWS EC2
• DigitalOcean Droplet

---

获取帮助

• 📖 完整文档: TEMPLATE_GUIDE.md
• 🏗️ 项目架构: CLAUDE.md
• 📋 部署指南: README.md
• ⚙️ 配置说明: backend/.env.example

---

下一步

1. ✅ 使用 create-from-template.sh 创建新项目
2. ✅ 配置 backend/.env
3. ✅ 安装依赖 (后端+前端)
4. ✅ 启动开发服务器
5. ✅ 开始开发你的功能

祝你的项目开发顺利! 🎉