insightoslog 1.0.7

InsightOS Log SDK - Unified log collection SDK

InsightOS Log SDK 统一日志接口

InsightOS Log SDK 是一个跨语言的统一日志接口实现，支持 C++、Go、Python 三种语言。该 SDK 遵循统一日志接口设计规范，提供结构化 JSON 日志输出、链路追踪、跨线程/协程上下文传播等功能。

---

测试目录

独立测试文件位于 test/ 目录下：

test/
├── cpp/      # C++ 测试 (xmake build && xmake run test)
├── go/       # Go 测试
└── python/   # Python 测试

---

目录

• 日志库架构
• 功能特性
• 日志结构
• 快速开始
  • C++ SDK
  • Go SDK
  • Python SDK
  • 使用示例
• API 参考
  • 初始化配置
  • 日志记录
  • 链路追踪
  • 上下文传播
• 输出模式
• 文件滚动策略
• 依赖说明
• 打包发布

---

日志库架构

InsightOS Log SDK 采用分层架构设计，每种语言都包含核心 SDK 层和 Wrapper 封装层。

架构分层

┌─────────────────────────────────────────────────────────────┐
│                     用户代码 (User Code)                     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Wrapper Layer (封装层)                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │ C++: Logger │  │ Go: Logger  │  │ Python:     │        │
│  │       Trace │  │       Trace │  │ 模块级函数  │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│         │                │                │                │
│  wrapper.hpp       wrapper.go        __init__.py          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Core SDK Layer (核心层)                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  初始化配置 (InitParam)                              │   │
│  │  日志消息 (Message/Builder)                         │   │
│  │  链路追踪 (Context/TraceID)                         │   │
│  │  上下文传播 (Propagation)                           │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                 Platform Layer (平台层)                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │ C++: spdlog │  │ Go: zap     │  │ Python:     │        │
│  │             │  │             │  │ logging     │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
└─────────────────────────────────────────────────────────────┘

各语言模块结构

C++ (cpp/)

cpp/
├── include/insightoslog/
│   ├── logging/
│   │   ├── logging.hpp    # 核心 SDK
│   │   ├── macros.hpp     # 宏定义
│   │   ├── message.hpp    # 消息结构
│   │   ├── context.hpp    # 上下文
│   │   ├── config.hpp     # 配置结构
│   │   ├── level.hpp      # 日志级别
│   │   ├── builder.hpp    # 建造者模式
│   │   └── api.hpp        # API 声明
│   └── wrapper/
│       └── wrapper.hpp    # Wrapper 封装 (Logger, Trace 类)
├── src/
│   └── logging.cpp        # 核心实现
└── xmake.lua

Go (go/)

go/
├── logging_sdk.go       # 根模块入口（Facade 重新导出层）
├── impl/                # impl 子模块（核心实现）
│   ├── api.go          # 核心 API（全局函数）
│   ├── config.go       # 配置结构
│   ├── context.go      # 上下文管理
│   ├── builder.go      # 建造者模式
│   ├── helper.go       # 辅助函数
│   ├── id.go           # TraceID/SpanID 生成
│   ├── init.go         # 初始化与链路追踪函数
│   ├── level.go        # 日志级别定义
│   ├── message.go      # 数据结构定义
│   └── go.mod          # 子模块 go.mod
└── wrapper/             # wrapper 子模块（面向对象封装）
    ├── wrapper.go       # Logger / Trace 类封装
    └── go.mod           # 子模块 go.mod

Python (python/)

python/
└── insightoslog/
    ├── __init__.py        # Wrapper 封装 + 核心实现
    ├── wrapper.py         # Wrapper 封装
    ├── _impl/
    │   └── __init__.py   # 核心实现
    └── pyproject.toml     # 包配置

Wrapper 层设计

Wrapper 层提供统一的面向对象 API，与 C++/Python 风格保持一致：

语言	Wrapper 类	便捷函数
C++	Logger, Trace	IOSLOG_INFO(), IOSLOG_DEBUG()
Go	Logger, Trace	Logger.Info(), Logger.Debug()
Python	模块级函数	info(), debug()

使用方式

C++:

#include <insightoslog/wrapper/wrapper.hpp>

using namespace insightoslog;

// 使用 Logger 类
Logger::Init({.service_name = "my-app"});
Logger::Info("Hello World");

// 使用 Trace 类
std::string trace_id = Trace::StartNewTrace();

Go:

import log "gitee.com/hong-zhenhuang/InsightOsLogSDK/go"

// 使用全局函数（推荐）
log.Init(log.InitParam{ServiceName: "my-app"})
log.Info("Hello World")

// 或使用 Logger/Trace 类（面向对象风格）
logger := log.NewLogger(log.LoggerInitParam{ServiceName: "my-app"})
logger.Info("Hello World")
traceID := log.StartNewTrace()

Python:

import insightoslog as log

# 使用模块级函数
log.init({"service_name": "my-app"})
log.info("Hello World")

# 或使用类封装
log.Logger.info("Hello from Logger")
trace_id = log.Trace.start_new_trace()

---

功能特性

1. 结构化 JSON 日志

• 按域（Domain）组织的 JSON 输出
• 支持的域：meta、resource、context、event、data、error、caller
• Pretty Print 格式（2 空格缩进）

2. 链路追踪（Tracing）

• 自动生成 trace_id 和 span_id
• 支持 HTTP Header 传播（X-InsightOSLog-TraceID、X-InsightOSLog-SpanID、X-InsightOSLog-ParentSpanID）
• 支持跨线程/协程自动上下文传播

3. 敏感信息过滤

• 自动过滤密码、Token、API Key 等敏感信息

4. 多语言支持

• C++ (使用 spdlog)
• Go (使用 zap)
• Python (使用标准 logging)

5. 多种输出模式

• stdout: 终端输出（带颜色）
• rotate_file: 滚动日志文件

6. 异步缓存层

• 内存缓冲区，日志先写入缓冲，定时刷新到输出
• 可配置队列大小和刷新间隔
• 大幅提升高并发场景性能

7. 建造者模式 API

• 链式调用支持
• 支持 on_request、with_data、with_error 等方法

---

日志结构

终端输出格式（stdout 模式）为：

LEVEL YYYY-MM-DDTHH:MM:SS.sss+08:00 [PID] {
  "meta": {...},
  "resource": {...},
  ...
}

各字段含义：

{
  "meta": {
    "level": "INFO",
    "time": "2026-03-11T10:00:00.000+08:00"
  },
  "resource": {
    "type": "ability",
    "name": "MyAbility",
    "instance_id": "abc-123",
    "host": "server-01",
    "pid": 12345
  },
  "context": {
    "trace_id": "550436d474944d77a6833ba578d53e6d",
    "span_id": "767461a9d8ea41f29c3defe40a755ede",
    "parent_span_id": ""
  },
  "event": {
    "msg": "Ability onStart",
    "request": {
      "method": "POST",
      "url": "/api/v1/ability",
      "latency_ms": 50
    }
  },
  "data": {
    "param": {"key": "value"},
    "result": {"status": "ok"},
    "truncate": false
  },
  "error": {
    "type": "RuntimeError",
    "message": "connection failed",
    "stacktrace": "..."
  },
  "caller": {
    "file": "main.cpp",
    "line": 42,
    "function": "main"
  }
}

说明：

• level 行颜色与 JSON 行保持一致（不同级别对应不同颜色）
• 时间格式统一为本地时区（+08:00），与 Go/C++/Python 三端一致

---

## 快速开始

### 配置文件格式

所有SDK都支持通过 `InsightOSLogConfig.yaml` 文件进行配置：

```yaml
# 配置文件示例 (InsightOSLogConfig.yaml)
level: INFO                    # 日志级别: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
service_type: "ability"        # 服务类型
service_name: "MyService"      # 服务名称
instance_id: "instance-001"   # 实例ID
log_root: "/root/InsightOSLog/logs"  # 日志根目录
output: "stdout"               # 输出模式: stdout / rotate_file

file:
  max_size: 5242880           # 单文件最大字节数 (5MB)
  max_files: 3                # 保留的旧日志文件数量

async:
  buffer_size: 4096           # 异步队列大小 (字节)
  flush_interval: 2           # 刷新间隔 (秒)

enable_tracing: true           # 是否启用链路追踪

1. C++ SDK

安装（推荐：APT 在线安装）

通过 APT 源直接安装（支持 amd64 / arm64）：

# 添加 APT 源（amd64）
echo "deb [trusted=yes arch=amd64] https://cdn.jsdelivr.net/gh/HongZH-XMU/insightoslog-apt@main/ stable main" | \
  sudo tee /etc/apt/sources.list.d/insightos.list

# 或 arm64
# echo "deb [trusted=yes arch=arm64] https://cdn.jsdelivr.net/gh/HongZH-XMU/insightoslog-apt@main/ stable main" | \
#   sudo tee /etc/apt/sources.list.d/insightos.list

# 更新并安装
sudo apt update
sudo apt install libinsightoslog-dev

提示： jsDelivr CDN 直接从 GitHub 仓库拉取文件，仓库公开即可使用，无需 GitHub Pages。如需国内极速访问或自定义域名，可在 GitHub 仓库 Settings > Pages 开启后，将 cdn.jsdelivr.net/gh/HongZH-XMU/insightoslog-apt@main 替换为你的自定义域名。

发布新版本后 CDN 未生效？ jsDelivr 会自动缓存（通常 5-15 分钟）。如需立即生效，执行以下命令刷新缓存： curl "https://purge.jsdelivr.net/gh/HongZH-XMU/insightoslog-apt@main/"

或通过手动下载 deb 安装：

# 从 GitHub APT 仓库下载最新版 deb 包
curl -LO https://cdn.jsdelivr.net/gh/HongZH-XMU/insightoslog-apt@main/pool/main/l/libinsightoslog-dev/libinsightoslog-dev_amd64.deb
sudo dpkg -i libinsightoslog-dev_amd64.deb
sudo apt install -f  # 修复依赖

或通过源码编译：

# 使用 xmake
cd cpp
xmake build

示例代码

#include <insightoslog/wrapper/wrapper.hpp>

using namespace insightoslog;

int main() {
    // 方式一：从配置文件初始化（默认 ./InsightOSLogConfig.yaml）
    Logger::InitFromConfig();

    // 或指定配置文件路径
    // Logger::InitFromConfig("/etc/insightos/InsightOSLogConfig.yaml");

    // 方式二：直接传入配置
    InitParam config;
    config.level = LogLevel::INFO;
    config.service_type = "ability";
    config.service_name = "MyAbility";
    config.instance_id = "abc-123";
    config.output = "stdout";  // 或 "rotate_file"

    Logger::Init(config);

    // 2. 开始新链路
    Trace::StartNewTrace();

    // 3. 记录日志
    Logger::Info("Application started");

    // 使用 fmt 格式化
    Logger::Info("User {} logged in", "john");

    // 或使用宏（更方便）
    IOSLOG_INFO("Application started");

    // 程序结束前调用 Shutdown 等待异步日志写入完成
    Logger::Shutdown();

    return 0;
}

编译运行

cd cpp
xmake build       # 编译 SDK

# 运行测试
cd ../test/cpp
xmake
xmake run

测试覆盖

C++ SDK 测试覆盖以下功能：

测试编号	测试名称	说明
1	基础初始化	SDK 初始化测试
2	便捷宏	INSIGHTOSLOG_INFO 等宏
3	fmt 格式化	格式化日志消息
4	建造者模式	链式调用 API
5	on_request / with_data	请求和数据日志
6	错误日志	错误信息记录
7	HTTP Header 传播	链路信息 Header 传播
8	跨线程传播	Context 跨线程继承
9	嵌套 Span	多级服务调用链路
10	make_context	手动创建 Context
11	LogBuilder 详细	建造者模式完整测试
12	多线程日志	并发写入测试
13	ID 生成	Trace ID / Span ID 生成
14	Header 常量	HTTP Header 常量验证
15	全局 Resource	Resource 信息测试
16	文件输出	rotate_file 模式测试
17	异步日志	异步队列测试
18	配置文件加载	InsightOSLogConfig.yaml 加载测试
19	RefreshPID	PID 刷新测试

---

2. Go SDK

安装

通过 go get 安装：

go env -w GOSUMDB=off
go env -w GOPROXY=direct
go get gitee.com/hong-zhenhuang/InsightOsLogSDK/go@v1.0.4

示例代码

package main

import (
    log "gitee.com/hong-zhenhuang/InsightOsLogSDK/go"
)

func main() {
    // 方式一：从配置文件初始化（默认 ./InsightOSLogConfig.yaml）
    log.InitFromConfig("./InsightOSLogConfig.yaml")

    // 方式二：直接传入配置
    log.Init(log.InitParam{
        Level:        log.LevelInfo,
        ServiceType:  "ability",
        ServiceName:  "MyAbility",
        InstanceID:   "abc-123",
        Output:       "stdout", // 或 "rotate_file"
        LogRoot:      "/var/log/insightos",
    })

    // 2. 开始新链路
    log.StartNewTrace()

    // 3. 记录日志
    log.Info("Application started")

    // 使用格式化
    log.Info("User {} logged in", "john")
}

func handler(w http.ResponseWriter, r *http.Request) {
    // 从 HTTP Header 提取链路信息
    log.ExtractFromHeaders(
        r.Header.Get("X-InsightOSLog-TraceID"),
        r.Header.Get("X-InsightOSLog-SpanID"),
        r.Header.Get("X-InsightOSLog-ParentSpanID"),
    )

    log.Info("Handling request")
}

运行测试

cd go
go test -v          # 运行所有测试
go test -v -run TestComplete  # 运行完整测试套件

测试覆盖

Go SDK 测试覆盖以下功能：

测试名称	说明
TestInit	SDK 初始化测试
TestConvenienceMacros	便捷日志函数
TestFmtFormatting	格式化日志
TestBuilderPattern	建造者模式
TestOnRequestWithData	请求和数据日志
TestErrorLogging	错误日志记录
TestHTTPHeaderPropagation	HTTP Header 传播
TestCrossGoroutinePropagation	跨 Goroutine 传播
TestNestedSpans	嵌套 Span 测试
TestMultiGoroutineLogging	多 Goroutine 并发日志
TestIDGeneration	ID 生成
TestContextFunctions	Context 函数
TestHeaderConstants	Header 常量
TestGlobalResource	全局 Resource
TestFileOutput	文件输出测试
TestAsyncLogging	异步日志测试
TestConfigLoading	配置文件加载

---

3. Python SDK

安装

pip install insightoslog

示例代码

import insightoslog as log

# 方式一：从配置文件初始化（默认 ./InsightOSLogConfig.yaml）
log.init_from_config()

# 或指定配置文件路径
# log.init_from_config("/etc/insightos/InsightOSLogConfig.yaml")

# 方式二：直接传入配置
log.init(log.InitParam(
    level=30,  # LogLevel.INFO
    service_type="ability",
    service_name="MyAbility",
    instance_id="abc-123",
    output="stdout",  # 或 "rotate_file"
    log_root="/var/log/insightos",
))

# 2. 开始新链路
log.LogContext.start_new_trace()

# 3. 记录日志
log.info("Application started")

# 使用格式化
log.info("User {} logged in".format("john"))


def handler(request):
    # 从 HTTP Header 提取链路信息
    log.LogContext.extract_and_inject_from_headers(
        request.headers.get("X-InsightOSLog-TraceID"),
        request.headers.get("X-InsightOSLog-SpanID"),
        request.headers.get("X-InsightOSLog-ParentSpanID"),
    )
    
    log.info("Handling request")

运行测试

cd test/python
python3 test_main.py

测试覆盖

Python SDK 测试覆盖以下功能：

测试编号	测试名称	说明
1	基础初始化	SDK 初始化测试
2	便捷宏	trace/info/warn/error 等函数
3	格式化	格式化日志消息
4	建造者模式	链式调用 API
5	on_request / with_data	请求和数据日志
6	错误日志	错误信息记录
7	HTTP Header 传播	链路信息 Header 传播
8	跨线程传播	Context 跨线程继承
9	ID 生成	Trace ID / Span ID 生成
10	Context 函数	Context 管理函数
11	嵌套 Span	多级服务调用链路
12	多线程日志	并发写入测试
13	Header 常量	HTTP Header 常量验证
14	全局 Resource	Resource 信息测试
15	文件输出	rotate_file 模式测试
16	异步日志	异步队列测试
17	配置文件加载	InsightOSLogConfig.yaml 加载测试
18	Refresh PID	PID 刷新测试
19	LogBuilder 详细方法	truncate/latency/with_result 等方法

---

导入使用

在任意电脑上安装和使用 InsightOS Log SDK，三种语言的导入方式如下：

C++ SDK

# 通过 APT 在线安装（推荐）
echo "deb [trusted=yes arch=amd64] https://cdn.jsdelivr.net/gh/HongZH-XMU/insightoslog-apt@main/ stable main" | \
  sudo tee /etc/apt/sources.list.d/insightos.list
sudo apt update && sudo apt install libinsightoslog-dev

# 或从 GitHub APT 仓库直接下载 deb
curl -LO https://cdn.jsdelivr.net/gh/HongZH-XMU/insightoslog-apt@main/pool/main/l/libinsightoslog-dev/libinsightoslog-dev_amd64.deb
sudo dpkg -i libinsightoslog-dev_amd64.deb
sudo apt install -f

# 编译（apt 安装后无需额外 -L/-I 参数）
g++ -o myapp main.cpp -linsightoslog-log -lpthread -ldl

Go SDK

# 1. 配置 Go 代理（Gitee 需要设置 GOPROXY）
go env -w GOPROXY=https://goproxy.cn,direct

# 2. 安装根模块（路径为 go/ 子模块）
go get gitee.com/hong-zhenhuang/InsightOsLogSDK/go@v1.0.4

# 如需单独使用子模块，可按需安装：
go get gitee.com/hong-zhenhuang/InsightOsLogSDK/go/impl@v1.0.4     # 核心实现层
go get gitee.com/hong-zhenhuang/InsightOsLogSDK/go/wrapper@v1.0.4   # 面向对象封装层

注意： Gitee 是公开平台，无需设置 GOPRIVATE，只需配置 GOPROXY 即可。

Python SDK

# 从 PyPI 安装
pip install insightoslog

---

API 参考

初始化配置

C++

struct InitParam {
    LogLevel level = LogLevel::INFO;
    std::string service_type;
    std::string service_name;
    std::string instance_id;
    std::filesystem::path log_root = "/root/InsightOSLog/logs";
    std::string output = "stdout";  // stdout / rotate_file
    int buffer_size = 4096;         // 异步队列大小
    std::chrono::seconds async_flush_interval{2};  // 刷新间隔（秒）
    bool enable_tracing = true;
    
    struct FileSpec {
        std::filesystem::path path;
        size_t max_size = 1048576 * 5;  // 5MB
        size_t max_files = 3;
    };
    FileSpec file;
};

void init(const InitParam& config);

Go

type InitParam struct {
    Level         LogLevel
    ServiceType   string
    ServiceName   string
    InstanceID    string
    LogRoot       string
    Output        string  // "stdout" / "rotate_file"
    MaxSize       int64   // 单文件最大字节数
    MaxFiles      int     // 最大文件数
    BufferSize    int     // 缓冲区大小（字节），0 表示同步
    FlushInterval int     // 刷新间隔（秒），0 表示不使用定时刷新
    EnableTracing bool
    Host          string
    PID           int
}

func Init(config InitParam)

Python

class InitParam:
    def __init__(self, level: int = LogLevel.INFO, 
                 service_type: str = "", 
                 service_name: str = "", 
                 instance_id: str = "",
                 log_root: str = "/tmp/insightoslog/logs", 
                 output: str = "stdout",
                 max_bytes: int = 10*1024*1024, 
                 backup_count: int = 5,
                 queue_size: int = 1000,     # 异步队列大小，0 表示同步
                 flush_interval: int = 2):   # 刷新间隔（秒）
        pass

def init(config: InitParam)

---

日志记录

便捷函数

| 级别 | C++ | Go | Python | | TRACE | Logger::Trace(msg) | LogTrace(msg) | trace(msg) | | DEBUG | Logger::Debug(msg) | Debug(msg) | debug(msg) | | INFO | Logger::Info(msg) | Info(msg) | info(msg) | | WARN | Logger::Warn(msg) | Warn(msg) | warn(msg) | | ERROR | Logger::Error(msg) | Error(msg) | error(msg) | | FATAL | Logger::Fatal(msg) | Fatal(msg) | fatal(msg) |

格式化日志

C++	Go	Python
info("msg {}", arg)	Info("msg {}", arg)	info("msg {}", arg)

建造者模式

// C++
Context ctx = current_context();
ctx.info("msg")
   .on_request({"POST", "/api", 100})
   .with_data(params, result)
   .with_error(error_obj)
   .truncate(true)
   .latency(50)
   .send();

// Go
ctx.Info("msg").
    OnRequest(EventRequest{Method: "POST", Path: "/api", LatencyMs: 100}).
    WithData(params, result).
    WithError(errorObj).
    Send()

# Python
ctx.info("msg") \
    .on_request(EventRequest(method="POST", path="/api", latency_ms=100)) \
    .with_data(params, result) \
    .with_error(error_obj) \
    .send()

---

链路追踪

开始新链路

// C++
Logger::StartNewTrace();

// Go
log.StartNewTrace()

# Python
LogContext.start_new_trace()

注入上下文

// C++
Logger::Inject(trace_id, span_id, parent_span_id);

// Go
log.Inject(traceID, spanID, parentSpanID)

# Python
LogContext.inject(trace_id, span_id, parent_span_id)

从 HTTP Header 提取

// C++
Logger::ExtractFromHeaders({
    .trace_id       = headers["X-InsightOSLog-TraceID"],
    .span_id        = headers["X-InsightOSLog-SpanID"],
    .parent_span_id = headers["X-InsightOSLog-ParentSpanID"],
});

// Go
log.ExtractFromHeaders(
    r.Header.Get("X-InsightOSLog-TraceID"),
    r.Header.Get("X-InsightOSLog-SpanID"),
    r.Header.Get("X-InsightOSLog-ParentSpanID"),
)

# Python
LogContext.extract_and_inject_from_headers(
    request.headers.get("X-InsightOSLog-TraceID"),
    request.headers.get("X-InsightOSLog-SpanID"),
    request.headers.get("X-InsightOSLog-ParentSpanID"),
)

---

上下文传播

手动传播（跨线程/协程）

// C++ - 父线程
Logger::PrepareForChildThread();
// 在新线程中
Logger::InheritFromPrepared();

// Go - 主 goroutine
log.PrepareForChildThread()
// 在新 goroutine 中
log.InheritFromPrepared()

# Python - 主线程
LogContext.prepare_for_child_thread()
# 在新线程中
LogContext.inherit_from_prepared()

自动传播

// C++ - 无需 ctx 参数，自动获取当前上下文
IOSLOG_INFO("msg");

// Go - 无需 ctx 参数，自动获取当前上下文
log.Info("msg")

# Python - 无需 ctx 参数，自动获取当前上下文
info("msg")

---

输出模式

模式	说明	颜色输出
stdout	输出到终端	✅ 是
rotate_file	输出到滚动日志文件	❌ 否

---

文件滚动策略

rotate_file 模式

当日志文件达到指定大小时，自动进行轮转：

参数	说明	默认值
max_size / MaxSize / max_bytes	单个日志文件最大字节数	10MB (C++/Python) / 5MB (Go)
max_files / MaxFiles / backup_count	保留的旧日志文件数量	3 (C++/Go) / 5 (Python)

日志文件路径

{log_root}/{service_type}/{service_name}.log

例如：/var/log/insightoslog/ability/MyAbility.log

---

依赖说明

C++ SDK

• spdlog
• nlohmann_json
• stduuid
• fmt

Go SDK

• github.com/google/uuid
• go.uber.org/zap
• go.uber.org/multierr

Python SDK

• 无外部依赖（使用标准库）

---

打包发布

使用 build_package.sh 一键打包 C++、Go、Python 三个 SDK 的发布产物，并自动更新 APT 在线仓库。

用法

# 默认版本 1.0.0，仅构建
./build_package.sh

# 指定版本
./build_package.sh 2.0.0

# 构建并发布（需设置环境变量）
PYPI_TOKEN=xxx ./build_package.sh 1.0.0

# 构建并自动推送到 APT 仓库（需设置 APT_REPO_REMOTE）
APT_REPO_REMOTE="[e-mail]:HongZH-XMU/insightoslog-apt.git" \
  ./build_package.sh 1.0.0

# 指定架构（C++ deb 包）
./build_package.sh 1.0.0 arm64

环境变量

变量	说明
PYPI_TOKEN	PyPI API 令牌（发布 Python 包）
GITEE_TOKEN	Gitee 个人访问令牌（发布 Go 模块）
APT_REPO_REMOTE	APT 仓库 Git remote 地址（自动推送 APT 仓库）

发布方式

语言	发布平台	用户安装命令
C++	APT 在线仓库（jsDelivr CDN）	apt install libinsightoslog-dev
Go	Go 官方模块代理（go/ 子目录）	go get gitee.com/hong-zhenhuang/InsightOsLogSDK/go@latest
Python	PyPI (.whl)	pip install insightoslog

C++ APT 在线仓库（推荐）

C++ SDK 通过 APT 源分发，用户只需一行命令即可安装：

# 添加 APT 源（amd64）
echo "deb [trusted=yes arch=amd64] https://cdn.jsdelivr.net/gh/HongZH-XMU/insightoslog-apt@main/ stable main" | \
  sudo tee /etc/apt/sources.list.d/insightos.list

# 安装
sudo apt update && sudo apt install libinsightoslog-dev

自动发布流程：

1. GitHub 创建空仓库 insightoslog-apt（不勾选 README）

2. 设置环境变量 APT_REPO_REMOTE

3. 运行 ./build_package.sh 自动构建、生成 APT 仓库、推送到 GitHub

4. 等待 GitHub 推送完成（约 10-30 秒）

5. 刷新 jsDelivr CDN 缓存（否则用户可能拿到旧版本）

   curl "https://purge.jsdelivr.net/gh/HongZH-XMU/insightoslog-apt@main/"
   

   提示： 如果只想刷新特定路径，可以指定精确路径，例如： curl "https://purge.jsdelivr.net/gh/HongZH-XMU/insightoslog-apt@main/dists/stable/"

6. 验证缓存已刷新：

   curl -s "https://cdn.jsdelivr.net/gh/HongZH-XMU/insightoslog-apt@main/dists/stable/main/binary-amd64/Packages" | grep "Version"
   

   输出 Version: X.X.X 即表示用户可以安装到最新版本。

GitHub Pages 不是必需的。jsDelivr 直接从 GitHub 仓库拉取文件，只要仓库是公开的即可使用。

输出结构

dist/{VERSION}/
├── cpp/
│   └── libinsightoslog-dev_{VERSION}_{ARCH}.deb   # deb 安装包
├── go/
│   ├── logging_sdk.go       # 根模块入口（Facade 层）
│   ├── go.mod               # 根模块 go.mod（含 replace 指令）
│   ├── go.sum
│   ├── impl/                # impl 子模块
│   │   ├── api.go
│   │   ├── config.go
│   │   └── ...
│   └── wrapper/             # wrapper 子模块
│       └── wrapper.go
└── python/
    └── insightoslog-{VERSION}-py3-none-any.whl              # wheel 安装包

各 SDK 打包说明

C++ SDK

通过 build_package.sh 自动编译 .so 动态库并打包成 .deb 安装包，同时自动推送到 GitHub APT 仓库。

发布方式：

1. 设置 APT_REPO_REMOTE 环境变量指向 insightoslog-apt 仓库
2. 运行 ./build_package.sh，自动构建、生成 APT 仓库、推送到 GitHub
3. 推送完成后执行 curl "https://purge.jsdelivr.net/gh/HongZH-XMU/insightoslog-apt@main/" 刷新 CDN 缓存
4. 验证：apt update && apt install libinsightoslog-dev 确认版本正确

使用方式：

# 添加 APT 源
echo "deb [trusted=yes arch=amd64] https://cdn.jsdelivr.net/gh/HongZH-XMU/insightoslog-apt@main/ stable main" | \
  sudo tee /etc/apt/sources.list.d/insightos.list

# 安装
sudo apt update && sudo apt install libinsightoslog-dev

# 编译
g++ -o myapp main.cpp -linsightoslog-log -lpthread -ldl

Go SDK

通过 build_package.sh 自动发布到 Git 仓库，Go 官方模块代理会自动同步。

发布方式：

1. 确保 Git remote 和 SSH key 已配置
2. 运行 ./build_package.sh 后自动创建 go/v{version} tag 并推送到 Gitee
3. Gitee 会自动同步到 proxy.golang.org

使用方式：

go get gitee.com/hong-zhenhuang/InsightOsLogSDK/go@v1.0.4

import (
    log "gitee.com/hong-zhenhuang/InsightOsLogSDK/go"
)

func main() {
    log.Init(log.InitParam{
        ServiceName: "my-app",
        Level:       log.LevelInfo,
    })
    log.Info("Hello World")
}

Python SDK

通过 build_package.sh 自动编译成 .whl 轮子文件并上传到 PyPI。

发布方式：

1. 设置 PYPI_TOKEN 环境变量
2. 运行 ./build_package.sh 后自动上传到 PyPI

使用方式：

pip install insightoslog

from insightoslog import init, InitParam, info

init(InitParam(
    service_name="my-app",
    level=30,
))
info("Hello from packaged SDK")

---

许可证

MIT License