v1.4.1 · 跨平台高性能

为 HarmonyOS 打造的
高性能 HTTP 服务器

基于 Rust 与 Tokio 异步运行时，采用 Master-Worker 多进程 × 协程架构，
支持 HTTP/2、HTTP/3 (QUIC)、反向代理、负载均衡、WebSocket 代理、
IP 限流防护、Session 管理、多站点虚拟主机等企业级特性。

快速安装 使用文档 GitCode
ohosHttp — 快速启动
$ ohosHttp -a 0.0.0.0:8080 -r ./www # 一行命令启动
 
╔═══════════════════════════════════════════════════════════════╗
║ ██████╗ ██╗ ██╗ ██████╗ ███████╗ ║
║ ██╔═══╝ ██║ ██║██╔═══╝ ██╔════╝ ║
║ ██║ ███████║██║ █████╗ ║
║ ██║ ██╔══██║██║ ██╔══╝ ║
║ ╚██████╗██║ ██║╚██████╗███████╗ ║
║ ╚═════╝╚═╝ ╚═╝ ╚═════╝╚══════╝ ║
║ ohosHttp v1.4.1 ─ 高性能 HTTP 服务器 ║
╚═══════════════════════════════════════════════════════════════╝
服务已就绪，按 Ctrl+C 停止服务
0+
功能特性
0万+
并发连接
0层
架构 (进程×协程)
0%
Rust 编写

🚀 功能特性

企业级 HTTP 服务器，30+ 功能开箱即用

静态文件服务

高效服务网站根目录的静态文件，支持目录列表和默认页面配置。

多站点 & 虚拟主机

基于域名的请求分发，支持在同一端口服务多个网站。

URL 重写（伪静态）

正则匹配 URL 重写规则，支持 ThinkPHP、Laravel、WordPress 等主流框架。

反向代理

将请求转发到后端服务，支持路径前缀匹配和 WebSocket 代理。

CGI 支持

支持 PHP、Python、Perl 等 CGI 脚本执行，可配置多解释器。

HTTPS / HTTP/2 / HTTP/3

TLS 加密、ALPN 自动协商 HTTP/2、UDP/QUIC 的 HTTP/3 支持。

负载均衡

加权轮询分发请求到多个后端服务器，提升服务吞吐能力。

IP 限流 & 黑名单

令牌桶算法每 IP 限流，CC 连接防护，自动封禁，IP 黑名单。

Session 管理

基于 Cookie 的内存 Session 管理，支持 TTL 过期自动清理。

管理 API

RESTful 管理接口（配置读写、启停控制、状态监控），含鸿蒙 ArkTS SDK。

CORS 跨域

可配置的跨域资源共享支持，灵活控制来源、方法和头部。

访问日志 & 轮转

自动轮转的访问日志，支持日期和大小切割，方便运维审计。

📥 安装指南

鸿蒙系统 & Linux 一键部署

1
方式 0：一键安装（推荐）

下载安装脚本，一键完成所有环境配置，适合鸿蒙系统快速部署。

# 下载并一键安装
chmod +x install.sh
./install.sh
2
方式 1：命令行快速启动

适合快速测试，一行命令直接启动 HTTP 服务。

# 绑定地址和端口，指定网站目录
./ohosHttp -a 127.0.0.1:8080 -r ./www

# 指定工作线程数
./ohosHttp --addr=0.0.0.0:8089 --root=/var/www --threads=4
3
方式 2：配置文件启动

适合生产环境，通过 TOML 配置文件完整管理所有站点。

# 生成默认配置文件
./ohosHttp --gen-config > config.toml

# 编辑配置文件后启动
./ohosHttp -c config.toml
4
方式 3：源码编译

从源码构建，适合自定义开发和交叉编译。

# 环境要求：Rust 1.75+
# 编译 release 版本
cargo build --release

# 输出在 target/release/ohosHttp
# 或使用构建脚本
./build.sh

📖 使用文档

完整的命令行选项与配置指南

命令行参数

参数简写说明
--addr-a绑定地址，如 127.0.0.1:8089
--root-r网站根目录（默认 ./www）
--config-c配置文件路径
--threads-t工作线程数（0=自动）
--gen-config—生成默认配置文件内容
--daemon-d守护进程模式（后台运行）
--interpreter—CGI 解释器路径
--cert—TLS 证书路径
--key—TLS 私钥路径
--http3-port—HTTP/3 (QUIC) 端口
--manage-auth—管理 API 认证 Token
--help-h显示帮助信息
--version-V显示版本信息

守护进程模式

# 后台运行
./ohosHttp -a 0.0.0.0:8080 -r ./www -d

# 指定 PID 文件
./ohosHttp -a 0.0.0.0:8080 -r ./www -d --pidfile /var/run/ohosHttp.pid

# 配置文件 + 守护进程
./ohosHttp -c config.toml -d --pidfile /var/run/ohosHttp.pid

# 停止服务
kill $(cat /var/run/ohosHttp.pid)

配置项速查表

配置项说明默认值
bind绑定地址和端口0.0.0.0:8080
root网站根目录./www
domains绑定的域名列表[]
workersWorker 进程数（0=CPU核数）0
cache_enabled是否启用缓存false
cache_ttl缓存过期时间1h
cache_max_size缓存最大大小100MB
upload_max_size上传最大大小10MB
directory_listing是否启用目录列表false
access_log访问日志路径—
cors_originCORS 允许的源*
allow_ip_access是否允许 IP 直连true

安全与限流配置

# IP 黑名单（支持 * 通配符）
blacklist = ["192.168.1.100", "10.0.0.*"]

# 限流配置
[server.rate_limit]
enabled = true
requests_per_second = 100 # 每IP每秒请求数
burst_size = 200 # 突发大小
connections_per_second = 20 # 连接速率
max_concurrent_connections = 100 # 最大并发连接数
ban_threshold = 20 # 自动封禁阈值
ban_duration_seconds = 300 # 封禁时长(秒)

# 自定义 IP 限流
per_ip_rates = {"192.168.1.50" = 500, "10.0.0.1" = 1000}

# 禁止访问目录/文件类型
forbidden_dirs = [".git", ".svn", "node_modules"]
forbidden_files = [".env", ".sql", ".bak"]

Session & 反向代理

# Session 配置
[server.session]
enabled = true
cookie_name = "OHOS_SESSION"
ttl = 3600

# 反向代理
[[server.location]]
path = "/api"
proxy_pass = "http://127.0.0.1:3000"

# WebSocket 代理（自动识别 Upgrade 头）
[[server.location]]
path = "/ws"
proxy_pass = "http://127.0.0.1:3001"

# 路径级 CGI
[[server.location]]
path = "/php"
cgi = { interpreter = "/usr/bin/php-cgi", extensions = [".php"] }

负载均衡配置

# 加权轮询分发到多个后端
[[server.location]]
path = "/api"
[[server.location.load_balance_targets]]
url = "http://127.0.0.1:8081"
weight = 3
[[server.location.load_balance_targets]]
url = "http://127.0.0.1:8082"
weight = 1
[[server.location.load_balance_targets]]
url = "http://127.0.0.1:8083"
weight = 1

HTTPS & HTTP/3 (QUIC)

# 启用 HTTPS（需要证书和私钥）
./ohosHttp -a 0.0.0.0:443 -r ./www --cert /path/to/cert.pem --key /path/to/key.pem

# 同时启用 HTTPS 和 HTTP/3
./ohosHttp -a 0.0.0.0:443 -r ./www --cert cert.pem --key key.pem --http3-port 443

# 配置文件中配置
cert = "./cert.pem"
key = "./key.pem"
http3_port = "443"

多站点配置示例

# 站点1：主站
[[server]]
bind = "0.0.0.0:8080"
root = "/var/www/main"
domains = ["example.com", "www.example.com"]
workers = 4

# 站点2：博客
[[server]]
bind = "0.0.0.0:8081"
root = "/var/www/blog"
domains = ["blog.example.com"]
workers = 2

# 启动所有站点
./ohosHttp -c config.toml --all

信号控制 & 热重启

信号动作
SIGTERM优雅关闭 — 停止接受新连接，等待活跃请求完成（最多30s），然后退出
SIGHUP热重启 — 重新加载配置，逐个重启 Worker，零停机
SIGCHLDWorker 崩溃自动恢复 — Master 自动 fork 新的 Worker 替换
# 热重启（重新加载配置）
kill -HUP $(cat /var/run/ohosHttp.pid)

# 优雅停止
kill -TERM $(cat /var/run/ohosHttp.pid)

🏗️ 架构设计

进程 × 协程 — 双层并发架构

╔══════════════════════════════════════════════════════════════╗ ║ Master 进程 ║ ║ 信号管理 (SIGTERM/SIGHUP/SIGCHLD) | Worker 监控 | 零停机热重启 ║ ╚══════════════════╦═══════════════════════╦══════════════════╝ ║ fork() ║ fork() ╔══════▼══════╗ ╔══════▼══════╗ ║ Worker 1 ║ ║ Worker N ║ ║ ─────────── ║ ║ ─────────── ║ ║ PID: 12345 ║ ... ║ PID: 1234N ║ ║ ║ ║ ║ ║ SO_REUSEPORT║ ║ SO_REUSEPORT║ ║ bind(:8080) ║ ║ bind(:8080) ║ ║ ║ ║ ║ ║ Tokio ║ ║ Tokio ║ ║ 单线程 ║ ║ 单线程 ║ ║ 事件循环 ║ ║ 事件循环 ║ ║ ──────── ║ ║ ──────── ║ ║ 协程 001 ║ ║ 协程 001 ║ ← 连接级 async 任务 ║ 协程 002 ║ ║ 协程 002 ║ ║ 协程 003 ║ ║ 协程 003 ║ ║ ... ║ ║ ... ║ ╚════════════╝ ╚════════════╝

层次说明

层单位并发方式
进程层Worker 进程fork()
协程层async 任务tokio::spawn

资源对比

特性进程协程
创建开销~10μs~10ns
内存占用~2MB~1KB
隔离性完全隔离进程内共享
并发数量数千数十万

核心优势

  • SO_REUSEPORT — 内核级负载均衡，无需反向代理
  • 进程隔离 — 一个 Worker 崩溃不影响其他
  • 无锁设计 — 没有共享状态，不需要互斥锁
  • 自动恢复 — Worker 崩溃后 Master 自动 fork 新进程
  • 零停机热重启 — SIGHUP 逐个替换 Worker

🔌 管理 API

RESTful 管理接口 · 鸿蒙 ArkTS 客户端 SDK

API 端点一览

方法路径说明认证
GET/_ohos/config获取服务器完整配置Bearer Token
PUT/_ohos/config更新配置（TOML 或 JSON）
GET/_ohos/status获取服务器运行状态
GET/_ohos/metrics获取运行时指标
POST/_ohos/pause暂停服务（新请求返回 503）
POST/_ohos/stop停止服务器
POST/_ohos/restart热重启服务器Bearer Token
POST/_ohos/start恢复服务Bearer Token

cURL 调用示例

# 获取运行状态
curl -H "Authorization: Bearer myToken" http://localhost:8089/_ohos/status

# 获取配置
curl -H "Authorization: Bearer myToken" http://localhost:8089/_ohos/config

# 更新配置
curl -X PUT -H "Authorization: Bearer myToken" \
  -H "Content-Type: text/plain" \
  -d '[[server]] bind = "0.0.0.0:8080" root = "./www"' \
  http://localhost:8089/_ohos/config

鸿蒙 ArkTS 客户端

ohosHttp 提供了完整的鸿蒙 ArkTS 管理 API 客户端 SDK，位于 examples/ohos-http-api.ets。

// 在鸿蒙 PC ArkTS 应用中调用
import { OhosHttpClient } from './ohos-http-api';

const client = new OhosHttpClient(
  'http://192.168.1.100:8089',
  'mySecretToken'
);

// 获取状态
const status = await client.getStatus();
console.log(status);

// 暂停服务
await client.pause();

// 热重启
await client.restart();

支持的方法：getConfig()、updateConfig()、getStatus()、getMetrics()、pause()、start()、restart()、stop()、isRunning()、isPaused()