5分钟上手Cowboy：从Hello World到HTTPS部署实战-优快云博客

5分钟上手Cowboy：从Hello World到HTTPS部署实战

【免费下载链接】cowboy Small, fast, modern HTTP server for Erlang/OTP. 项目地址: https://gitcode.com/gh_mirrors/co/cowboy

Cowboy是一个轻量级、高性能的HTTP服务器，专为Erlang/OTP平台设计。作为现代Web开发的理想选择，它支持HTTP/1.1、HTTP/2、WebSocket等多种协议，且内存占用低、响应速度快。本文将带你快速掌握Cowboy的核心功能，从基础安装到生产环境部署，全程实践导向，让你在最短时间内具备实战能力。

环境准备与快速启动

Cowboy基于Erlang/OTP构建，需先确保环境中已安装Erlang 24.0或更高版本。通过GitCode仓库获取源码：

git clone https://gitcode.com/gh_mirrors/co/cowboy
cd cowboy

项目提供了丰富的示例代码，其中hello_world是入门最佳选择。进入示例目录并编译运行：

cd examples/hello_world
make
./_build/default/rel/hello_world/bin/hello_world start

访问http://localhost:8080，若看到"Hello world!"，则表示服务启动成功。核心代码位于examples/hello_world/src/toppage_h.erl，其中init/2函数处理HTTP请求并返回响应：

init(Req0, Opts) ->
    Req = cowboy_req:reply(200, #{
        <<"content-type">> => <<"text/plain">>
    }, <<"Hello world!">>, Req0),
    {ok, Req, Opts}.

路由配置与请求处理

Cowboy的路由系统通过cowboy_router模块实现，负责将请求分发到对应的处理器。在examples/hello_world/src/hello_world_app.erl中，路由规则定义如下：

Dispatch = cowboy_router:compile([
    {'_', [
        {"/", toppage_h, []}
    ]}
]),
{ok, _} = cowboy:start_clear(http, [{port, 8080}], #{
    env => #{dispatch => Dispatch}
}),

'_'表示匹配所有主机
{"/", toppage_h, []}将根路径请求交给toppage_h处理器处理
cowboy:start_clear/3启动HTTP监听器，监听8080端口

路由支持路径参数、通配符等高级功能，例如：

{"/user/:id", user_h, []}  % 匹配/user/123，参数id=123
{"/static/[...]", cowboy_static, {priv_dir, my_app, "static"}}  % 静态文件服务

详细路由规则可参考doc/src/manual/cowboy_router.asciidoc。

从HTTP到HTTPS：安全通信配置

生产环境需启用HTTPS加密通信。Cowboy提供cowboy:start_tls/3函数快速配置SSL。以examples/ssl_hello_world为例，关键配置如下：

{ok, _} = cowboy:start_tls(https, [
    {port, 8443},
    {certfile, PrivDir ++ "/ssl/cert.pem"},
    {keyfile, PrivDir ++ "/ssl/key.pem"}
], #{env => #{dispatch => Dispatch}}),

生成自签名证书（开发环境）：

mkdir -p priv/ssl
openssl req -new -newkey rsa:2048 -nodes -keyout priv/ssl/key.pem -out priv/ssl/cert.pem -x509 -days 365

生产环境注意事项：

使用CA签发的证书，避免浏览器安全警告
配置证书链文件（cacertfile）
启用TLS 1.2+，禁用不安全加密套件

启动HTTPS服务后，访问https://localhost:8443验证配置。

生产部署最佳实践

1. 应用监控

使用observer工具监控Erlang节点状态
配置cowboy_metrics_h收集请求指标：

metrics_callback(Metrics) ->
    io:format("Metrics: ~p~n", [Metrics]).

start() ->
    cowboy:start_clear(http, [{port, 8080}], #{
        middlewares => [cowboy_metrics_h, cowboy_router, cowboy_handler],
        metrics_callback => fun metrics_callback/1
    }).

2. 性能优化

启用压缩中间件cowboy_compress_h：

middlewares => [cowboy_compress_h, cowboy_router, cowboy_handler]

调整连接池大小：

{num_acceptors, 10},  %  acceptor进程数
{max_connections, 1024}  % 最大并发连接数

3. 高可用部署

使用systemd或进程管理工具管理进程
配置示例（systemd service文件）：

[Unit]
Description=Cowboy HTTP Server
After=network.target

[Service]
User=www-data
WorkingDirectory=/opt/cowboy_app
ExecStart=/opt/cowboy_app/bin/myapp start
ExecStop=/opt/cowboy_app/bin/myapp stop
Restart=always

[Install]
WantedBy=multi-user.target

功能扩展与生态集成

Cowboy提供多种内置中间件和处理器，满足不同场景需求：

RESTful API：使用cowboy_rest模块，参考examples/rest_hello_world
WebSocket通信：通过cowboy_websocket实现实时通信，示例见examples/websocket
静态文件服务：cowboy_static模块高效提供静态资源，支持范围请求和缓存控制
Server-Sent Events：服务端推送技术，示例见examples/eventsource

常见问题与调试技巧

1. 端口占用错误（eaddrinuse）

{error, eaddrinuse}  # 端口已被占用

解决：更换端口或终止占用进程：fuser -k 8080/tcp

2. 路由不匹配（404 Not Found）

检查路由配置是否正确编译
使用cowboy_req:uri(Req)打印请求URI进行调试
启用日志中间件跟踪请求流程

3. 性能瓶颈排查

使用cowboy_tracer_h跟踪请求处理时间
检查Erlang VM参数：+P 1024000（最大进程数）、+K true（启用 kernel poll）

总结与进阶资源

通过本文，你已掌握Cowboy的核心用法，从基础HTTP服务到HTTPS安全配置，再到生产环境部署。Cowboy作为Erlang生态的轻量级HTTP服务器，兼具高性能和灵活性，适合构建各类Web应用。

5分钟上手Cowboy：从Hello World到HTTPS部署实战