NeHex 部署&使用教程

NeHex是一个基于AI的个人空间解决方案，采用Python + FastAPI + PostgreSQL 架构搭建，轻量高效，支持文章编辑、相册管理、草稿保存等核心功能，适用于个人博客、个人展示空间等场景。

一、系统要求

确保服务器满足以下最低配置，避免部署后出现性能或兼容性问题：

linux / macos （不推荐Windows系统，兼容性较差）
Linux 内核版本 >= 4.19
内存（Memory）>= 1.5G
Docker 及 Docker Compose 已安装（推荐最新稳定版）

二、安装部署步骤

2.1 拉取项目文件

推荐使用手动下载稳定版（避免Git拉取的开发版存在未知问题），步骤如下：

访问NeHex官方发行页：https://github.com/NeHex/nehex-core/releases
下载最新稳定版（当前最新为 v1.0.2），选择适合服务器系统的压缩包
将压缩包上传至服务器目标目录（如 /opt/nehex），并解压：
unzip nehex-core-v1.0.2.zip -d nehex-core

*不推荐 Git 拉取方式：*直接拉取仓库主分支可能包含未稳定的代码，若需尝试，执行命令：
git clone git@github.com:NeHex/nehex-core.git

2.2 配置 .env 文件（关键步骤）

项目依赖 .env 文件配置运行参数，需严格按照以下步骤操作，避免报错：

进入项目根目录，复制示例配置文件为正式配置文件：
cp .env.example .env
使用 vi 或 nano 编辑 .env 文件（以 vi 为例）：
vi .env
按以下配置修改（标注 必填修改 的项必须更改，其余可默认）：

APP_NAME=NeHex Core API
APP_VERSION=v1.0.2  # 与下载的版本保持一致
APP_ENV=dev  # 生产环境可改为 prod
APP_PORT=7878     <-- 后台端口，可自定义，需确保端口未被占用
CORS_ALLOW_ORIGINS=http://127.0.0.1:3000,http://localhost:3000     <-- 允许的前端域名，多个用逗号分隔（解决跨域问题）
CORS_ALLOW_CREDENTIALS=true
ADMIN_MANAGER_WEB=/nehex-admin     <-- 后台管理页面路径，默认即可
ADMIN_MANAGER_BUILD_ON_STARTUP=false     <-- 建议关闭，避免启动时耗时构建
ADMIN_API_SECRET=please-change-me     <-- 【必填修改】后台API密钥，自定义复杂字符串（如随机生成32位字符）
ADMIN_API_CLIENT_ID=nehex-vuetify-admin     <-- 后台客户端ID，默认即可
ADMIN_API_TOKEN_TTL_SECONDS=43200
ADMIN_COOKIE_DOMAIN=     <-- 建议留空（本地部署），域名部署可填写主域名（如 .example.com）
ADMIN_PUBLIC_COOKIE_DOMAIN=     <-- 【推荐配置】填写你的域名（如 .example.com），用于前端读取登录Cookie（v1.0.2新增）
SIMPLE_CACHE_MAX_ENTRIES=1024  # 内存缓存上限，默认即可
REDIS_ENABLED=true  # 启用Redis缓存（推荐开启，提升性能）
REDIS_URL=redis://127.0.0.1:6379/0  # Redis地址，本地部署默认即可
REDIS_CACHE_PREFIX=nehex:cache:
REDIS_CONNECT_RETRY_SECONDS=30
REDIS_SOCKET_CONNECT_TIMEOUT=1.0
REDIS_SOCKET_TIMEOUT=1.5

# 数据库配置（【必填修改】）
DB_HOST=127.0.0.1
DB_DRIVER=postgresql
DB_PORT=5432
DB_NAME=nehex_dtbs     <-- 自定义数据库名称
DB_USER=nehex_dtbs     <-- 自定义数据库账户
DB_PASSWORD=change-me     <-- 自定义数据库密码（复杂密码，避免泄露）
DB_URL=

DB_POOL_SIZE=10
DB_MAX_OVERFLOW=20
DB_POOL_RECYCLE=1800
DB_POOL_TIMEOUT=30
DB_CONNECT_TIMEOUT=5
DB_READ_TIMEOUT=15
DB_WRITE_TIMEOUT=15
DB_AUTO_CREATE_TABLES=false  # 不自动建表，避免误操作
DB_STARTUP_MAX_RETRIES=30
DB_STARTUP_RETRY_INTERVAL_SECONDS=2
TZ=Asia/Shanghai  # 时区，默认亚洲/上海，无需修改

注意：v1.0.2版本新增 ADMIN_COOKIE_DOMAIN 和 ADMIN_PUBLIC_COOKIE_DOMAIN 两个变量，若遗漏配置，会导致后台登录后前端无法读取Cookie，出现登录失效问题。

2.3 启动服务

配置完成后，通过Docker Compose启动服务，执行以下命令（项目根目录下）：

docker compose up -d --build

命令说明：

up -d：后台启动容器
--build：重新构建镜像（首次启动或更新版本时必须添加）

启动后，可执行 docker ps 查看容器状态，若状态为Up，则启动成功。

2.4 反向代理配置（可选，推荐）

若需通过域名访问（而非IP+端口），需配置反向代理，以Nginx为例：

server {
    listen 80;
    server_name your-domain.com;  # 替换为你的域名

    location / {
        proxy_pass http://127.0.0.1:7878;  # 代理到NeHex后台端口（与.env中APP_PORT一致）
        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;  # 支持HTTPS反向代理（v1.0.1+新增）
    }
}

配置完成后，重启Nginx：systemctl restart nginx

2.5 首次安装配置

启动成功后，访问后台管理页面：

无反向代理：http://服务器IP:7878/nehex-admin
有反向代理：http://你的域名/nehex-admin

按照页面指引完成首次安装（设置管理员账号、密码等），安装完成后即可登录后台。

三、常见报错解决（结合实际报错信息）

3.1 报错：URL拼写可能存在错误，请检查（对应 http://127.0.0.1:7878 报错）

检查 .env 文件中 APP_PORT 是否为 7878，若修改过端口，访问时需对应替换
检查Docker容器是否启动：docker ps，若未启动，执行 docker compose up -d
检查服务器防火墙是否放行对应端口（如7878）：
CentOS：firewall-cmd --permanent --add-port=7878/tcp && firewall-cmd --reload
Ubuntu：ufw allow 7878 && ufw reload

3.2 报错：网页解析失败，可能是不支持的网页类型（对应 http://127.0.0.1:3000 报错）

检查 CORS_ALLOW_ORIGINS配置，确保包含前端地址（如 http://127.0.0.1:3000），多个地址用逗号分隔
确认前端服务已启动（若有独立前端），或检查 ADMIN_MANAGER_WEB 路径是否正确（默认 /nehex-admin）
若无需前端服务，可暂时删除 CORS_ALLOW_ORIGINS 中的前端地址（不推荐，可能影响后台操作）

3.3 其他常见问题

登录后无法操作：检查 ADMIN_COOKIE_DOMAIN 和 ADMIN_PUBLIC_COOKIE_DOMAIN 配置，域名部署需填写正确域名，本地部署留空
数据库连接失败：检查 .env 中数据库配置（DB_HOST、DB_USER、DB_PASSWORD等），确保PostgreSQL服务正常
缓存异常：若启用Redis，检查Redis服务是否启动，Redis_URL配置是否正确

四、更新指南

备份现有 .env 文件（关键！新增变量需手动添加）：
cp .env .env.bak
拉取新版本文件
重建并启动容器：
docker compose up -d --build

五、功能说明（v1.0.2 新增特性）

编辑器优化：修改布局，新增快捷操作按钮，提升编辑体验
草稿功能：支持草稿保存，后台可按“已发布”“草稿”分类管理
备份功能：后端支持备份，多余备份文件可手动删除
Cookie优化：登录后向浏览器写入前端可读取的Cookie，提升登录稳定性
相册编辑器：优化样式，提升视觉体验
邮件通知：新增直达链接，点击即可跳转对应内容

六、问题反馈

若部署或使用过程中遇到其他问题，可通过以下方式反馈：

GitHub Issues：https://github.com/NeHex/nehex-core/issues（当前Issues数量为0，可直接提交新问题）
邮件联系：i@uegee.com

（注：文档部分内容可能由 AI 生成）