Skip to content

README_zh.md

Latest commit

 

History

History
166 lines (118 loc) · 3.96 KB

README_zh.md

File metadata and controls

166 lines (118 loc) · 3.96 KB

IP服务器

一款基于Rust的轻量级服务器，用于管理和检索设备的IP地址，通过认证API进行访问。

功能特性

  • IPv6支持: 服务器默认监听IPv6地址
  • 身份验证: 所有API端点都需要使用认证码进行身份验证
  • 设备跟踪: 存储和检索设备IP地址，具有自动过期功能
  • 命令行接口: 通过CLI选项配置认证码和超时时间
  • 全面日志记录: 详细记录所有客户端操作
  • 强大的错误处理: 使用thiserror进行全面错误处理
  • 模块化架构: 遵循行业标准的良好组织代码模块
  • RESTful API: 具有GET/POST端点的简洁API
  • 线程安全: 使用DashMap进行并发访问
  • 自包含配置: 配置文件与可执行文件位于同一目录

先决条件

  • Rust 2024版本
  • Cargo

安装

  1. 克隆仓库
  2. 导航到项目目录
  3. 构建项目:
cargo build --release

配置

服务器支持命令行参数和配置文件进行设置。配置文件是与可执行文件位于相同目录中的config.toml。如果文件不存在，则会使用默认值创建:

auth_code = "basic_auth_code"
expire_time = 86400  # 24小时，以秒为单位

命令行选项

服务器接受覆盖配置文件设置的命令行参数:

./ip_server [OPTIONS]

选项:

  • -a, --auth-code <AUTH_CODE>: 设置授权码
  • -e, --expire-time <EXPIRE_TIME>: 设置超时时间（秒）
  • --save-config: 将参数保存到配置文件
  • -h, --help: 显示帮助信息

命令行参数优先于配置文件中的值。如果提供了--save-config标志，当前参数将被保存到配置文件中。

日志

服务器将所有操作记录到与可执行文件位于相同目录中的.log文件中。每个日志条目包含:

  • 操作的时间戳
  • 客户端IP地址
  • 操作类型（GET_IP或UPDATE_IP）
  • 详细的操作信息

示例日志条目:

[2026-02-01 01:45:24] IP: ::1, Operation: UPDATE_IP, Details: Successfully updated IP for device: test_device, IP: ::1

API端点

健康检查

  • GET / - 检查服务器是否正在运行

响应: "The server is running now."

更新设备IP

  • POST /update - 注册或更新设备的IP地址

请求体:

{
  "auth_code": "your_auth_code",
  "device_name": "device_identifier"
}

响应: 成功时返回 "ok"

状态码:

  • 200: 成功
  • 401: 无效的认证码
  • 500: 内部服务器错误

获取设备IP

  • POST /get - 检索设备的IP地址

请求体:

{
  "auth_code": "your_auth_code",
  "device_name": "device_identifier"
}

响应: 成功时返回设备的IP地址字符串

状态码:

  • 200: 成功，返回IP地址
  • 401: 无效的认证码
  • 404: 设备未找到
  • 410: 设备记录已过期
  • 500: 内部服务器错误

运行服务器

使用默认配置启动服务器:

cargo run

或使用自定义参数:

# 通过CLI设置认证码和超时时间
cargo run -- --auth-code "my_secret_code" --expire-time 7200

# 设置参数并保存到配置文件
cargo run -- --auth-code "my_secret_code" --expire-time 7200 --save-config

服务器将在 [::1]:3000 (IPv6本地主机) 上监听。

示例用法:

# 更新设备IP
curl -X POST http://[::1]:3000/update \
  -H "Content-Type: application/json" \
  -d '{"auth_code": "basic_auth_code", "device_name": "my_device"}'

# 获取设备IP
curl -X POST http://[::1]:3000/get \
  -H "Content-Type: application/json" \
  -d '{"auth_code": "basic_auth_code", "device_name": "my_device"}'

架构

服务器使用Axum作为Web框架，Tokio用于异步运行时。代码组织成模块化组件:

  • models: 数据结构和状态管理
  • handlers: API端点处理器
  • config: 配置管理
  • logging: 日志功能
  • errors: 自定义错误类型

设备信息存储在支持线程安全的DashMap中，在检索时进行自动过期检查。配置和日志文件存储在与可执行文件相同的目录中。

许可证

MIT许可证