Qexo（Hexo在线管理后台）使用详细步骤

子非鱼2025-03-182025-03-18

以下是基于知识库信息和常见部署流程整理的 Qexo（Hexo在线管理后台）使用详细步骤，按照分步指南整理：

Qexo 使用详细步骤

一、环境准备

安装依赖工具：
- Git：用于代码版本控制。
- Python 3.x：Qexo 后端运行环境。
- Node.js & npm（可选）：部分部署场景可能需要。
- Hexo：确保已搭建好 Hexo 博客（需关联到 Qexo 管理）。
准备 Hexo 博客仓库：
- 将 Hexo 博客代码托管到 GitHub/GitLab 等代码仓库（需公开或私有访问权限）。

二、部署 Qexo 后台

方法 1：Vercel 一键部署（推荐）

步骤 1：创建 Vercel 项目

访问 Qexo 官方 Vercel 部署链接，选择克隆仓库 https://github.com/Qexo/Qexo.git。
使用 GitHub/GitLab 账号登录，选择仓库名称和分支（默认 main）。
点击 Deploy 启动部署。

步骤 2：配置数据库

创建 PostgreSQL 数据库：
- 在 Vercel 控制台选择 Vercel Storage → Create Database → 选择 PostgreSQL。
- 记录数据库连接信息（Host、Port、User、Password、DB Name）。
绑定数据库到项目：
- 进入项目设置 → Connect to Project，选择刚创建的数据库。
- 重新部署项目（点击 Redeploy）。

步骤 3：设置环境变量

在 Vercel 项目设置中添加以下变量（参考数据库信息）：

PG_HOST=your_postgresql_host
PG_PORT=5432
PG_USER=your_postgresql_user
PG_DB=your_postgresql_db
PG_PASS=your_postgresql_password

步骤 4：解决常见问题

**报错 pip not found**：
- 进入项目设置 → Settings → Environment → Node.js version，设置为 18.x（参考知识库 Issue #524）。
部署失败：
- 确保所有环境变量填写正确，且数据库区域与项目区域一致（如 Washington, D.C., USA (East)）。

方法 2：本地部署（备用方案）

步骤 1：克隆项目

1 2	git clone https://github.com/Qexo/Qexo.git cd Qexo

步骤 2：安装依赖

1	pip install -r requirements.txt

步骤 3：配置数据库

创建数据库文件 db.sqlite3：
1
2
mkdir db && cd db
touch db.sqlite3

运行数据库迁移：

1 2	python3 manage.py makemigrations python3 manage.py migrate

步骤 4：启动服务

1	python3 manage.py runserver 0.0.0.0:8000 --noreload

访问 http://localhost:8000 初始化后台。

三、配置 Qexo 后台

初始化管理员账号：
- 首次访问部署后的 Qexo 域名（如 https://qexo.yourdomain.com），设置：
  - 用户名和密码（用于登录后台）。
  - API 密钥（可留空自动生成）。
配置 GitHub/GitLab 权限：
- GitHub Token：
  1. 在 GitHub → Settings → Developer settings → Personal access tokens 创建新 Token。
  2. 赋予 repo 和 workflow 权限（勾选 repo 和 workflow 相关选项）。
  3. 将生成的 Token 填入 Qexo 后台的 GitHub 密钥字段。
- 仓库地址：填写 Hexo 博客的 Git 仓库 URL（如 https://github.com/yourname/your-hexo-blog.git）。
- 分支：选择 Hexo 博客的主分支（如 main 或 master）。
配置 Vercel 信息（可选）：
- 如果使用 Vercel 部署 Hexo，需填写 Vercel 的 Project ID 和 Token：
  - Project ID：在 Vercel 项目设置 → General 中获取。
  - Token：在 Vercel → Settings → Account settings → Security → Tokens 创建新 Token。

四、使用 Qexo 管理 Hexo 博客

1. 发布文章

登录 Qexo 后台 → 进入 文章管理 → 点击 新建文章。
编写文章内容（支持 Markdown）→ 点击保存或发布。
发布后，文章会自动推送到 Hexo 仓库，并触发部署（需配置 CI/CD，如 GitHub Actions）。

2. 配置 Hexo 部署

确保 Hexo 仓库已配置 CI/CD 流水线（如 GitHub Actions），以便 Qexo 发布文章后自动部署到网站。

3. 更换主题

在本地 Hexo 环境中更换主题（参考主题文档）。
将修改后的配置推送到 Git 仓库 → 在 Qexo 后台设置中更新仓库分支信息。

五、常见问题解决

1. 部署后无法访问后台

域名被屏蔽：在 Vercel 绑定自有域名（如 qexo.yourdomain.com），避免使用 Vercel 默认域名。
端口占用：本地部署时尝试更换端口（如 python3 manage.py runserver 0.0.0.0:8080）。

2. 数据库连接失败

检查环境变量是否填写正确（如 PG_HOST 是否为 PostgreSQL 的公网地址）。
确保数据库防火墙允许 Vercel 服务器 IP 访问（如使用 PlanetScale 需开启网络权限）。

3. 文章无法发布到 GitHub

检查 GitHub Token 是否具有 repo 和 workflow 权限。
确保 Hexo 仓库地址和分支名称填写正确。

六、高级配置

1. 使用 Supervisor 常驻进程（本地部署）

# 安装 Supervisor
sudo apt install supervisor

# 创建配置文件 /etc/supervisor/conf.d/qexo.conf
[program:qexo]
command=python3 manage.py runserver 0.0.0.0:8000 --noreload
directory=/path/to/Qexo
autostart=true
autorestart=true
user=root
stdout_logfile=/var/log/qexo.out.log
stderr_logfile=/var/log/qexo.err.log

2. 配置 Nginx 反向代理（本地部署）

server {
    listen 80;
    server_name qexo.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

七、总结

通过以上步骤，你可以成功部署 Qexo 并管理 Hexo 博客。核心要点包括：

Vercel 部署：快速上手，适合新手。
数据库配置：确保连接信息正确。
权限设置：GitHub Token 和 Vercel 密钥需谨慎保管。
CI/CD 集成：保证文章发布后自动更新网站。

如果遇到具体问题，可参考 Qexo 的 GitHub Issues 或知识库中的解决方案。