本地开发指南

在本地运行 Huper 琥珀开发环境，适合开发和测试。

---

📦 前置要求

要求	版本	说明
Python	3.8+	后端运行
Node.js	16+	前端构建（可选）
Git	最新	代码克隆
macOS	10.15+	上下文捕获（可选）

---

🚀 快速启动

第一步：克隆代码

# 克隆仓库（需要权限）
git clone https://github.com/ankechenlab-node/huper.git
cd huper

第二步：安装依赖

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装 Python 依赖
pip install -r requirements.txt

第三步：初始化数据库

# 创建 SQLite 数据库
python init_db.py

第四步：启动服务

# 启动后端服务
python app.py

# 访问 http://localhost:5000

---

🔧 开发模式

前端开发（可选）

# 进入前端目录
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

后端开发

# 启用调试模式
export FLASK_DEBUG=1
python app.py

# 运行测试
pytest tests/

---

📁 项目结构

huper/
├── app.py              # Flask 主应用
├── init_db.py          # 数据库初始化
├── requirements.txt    # Python 依赖
├── data/
│   └── huper.db        # SQLite 数据库
├── frontend/           # 前端代码（可选）
│   ├── src/
│   └── package.json
└── tests/              # 测试用例

---

🔑 配置说明

环境变量

创建 .env 文件：

# 数据库路径
DATABASE_URL=sqlite:///data/huper.db

# JWT 密钥（生产环境请修改）
JWT_SECRET=your-secret-key-here

# 加密密钥（32 字节）
ENCRYPTION_KEY=your-32-byte-key-here

# 调试模式
FLASK_DEBUG=1

配置文件

# config.py
class Config:
    SECRET_KEY = os.environ.get('SECRET_KEY') or 'dev-key'
    SQLALCHEMY_DATABASE_URI = 'sqlite:///huper.db'
    SQLALCHEMY_TRACK_MODIFICATIONS = False

---

🧪 测试

运行单元测试

# 安装测试依赖
pip install pytest pytest-cov

# 运行测试
pytest tests/ -v

# 查看覆盖率
pytest tests/ --cov=app --cov-report=html

测试上下文捕获（仅 macOS）

# 需要 Accessibility 权限
# 系统偏好设置 → 安全性与隐私 → 隐私 → 辅助功能
# 添加终端应用

---

🐛 常见问题

Q: 启动失败，提示端口占用

A: 修改端口：

export PORT=5001
python app.py

Q: 数据库文件不存在

A: 运行初始化：

python init_db.py

Q: 前端构建失败

A: 检查 Node.js 版本：

node --version  # 需要 16+
npm --version

Q: 语义搜索不工作

A: 检查向量索引：

# 重新构建索引
python rebuild_index.py

---

📚 下一步

• VPS 部署指南 - 生产环境部署
• 配置优化 - 高级配置项
• 故障排查 - 常见问题解决

---

提示：开发完成后，记得运行测试确保功能正常。