网络安全【免费下载链接】portmaster Love Freedom - ❌ Block Mass Surveillance项目地址https://gitcode.com/gh_mirrors/po/portmaster点击查看免费下载Portbase 是 Portmaster 与 Gate17 两个产品共用的 Go 服务端基础库base 代码它把日志、模块化启动、动态配置、构建信息、随机数与数据库等服务service而非工具tool所需的公共能力沉淀为一套可复用的基础设施。本指南以 base/README.md 为骨架结合当前仓库源码讲解每一组件的设计理念、核心 API 与实战用法读完后你可以直接用 Portbase 的思路搭建一个具备多阶段启动、热更新配置与同步数据库的服务主程序。Portbase 是什么Portbase 的定位非常明确它为**服务service**提供基础能力而不是为命令行工具tool提供框架。它在 base/README.md 中开宗明义地列出了包含的组件组件职责log极快且美观的日志系统modules多阶段、依赖感知的启动流程同时管理任务config简单、实时更新、极快的配置存储info轻松为构建打上版本、commit 哈希等标签formats一些顺手的数据编码库rng可喂养feedable的 CSPRNGdatabase带 hooks、可与 struct 轻松集成的智能可同步数据库基于多后端 bucketsapi面向数据库的 websocket 接口可扩展自定义 http 处理器这个项目最初就是为了同时承载 Portmaster 与 Gate17 的基础代码而创建的将来也会继续围绕这两个产品演进。README 同时给出了一个明确的态度Portbase 相当贴合其自身需求并非对所有人通用如果读者有改进想法可以提交 issue但维护者也可能建议你 fork 一份去做自己的定制。项目处于活跃维护状态欢迎提交 issue。log以速度为首要目标的日志系统log组件在 base/log 目录下实现它的核心设计目标有两个尽可能快日志调用只做最小处理然后把日志消息发送到一个 channel让服务可以立刻继续做正事写日志的动作延后执行美观无论是信息的形式格式还是呈现方式都力求优雅。从 base/log/logging.go 的源码注释可以看到这套设计的具体形态日志函数先检查是否启用了基于文件的级别过滤再检查当前级别是否激活然后通过一个大容量缓冲 channellogBuffer chan *logLine把数据送往后台后台Backend等待有空闲时再真正写日志支持写入文件夹缓冲 滚动文件 appender和/或控制台控制台把 INFO 以上级别输出到 stderrchannel 有过缓冲保护当缓冲区满时立即触发一次写入还有反导入环Anti-Importing-Loop设计所有包都导入 logginglogging 由主模块配置并被授予对配置和任务管理器的访问权。log定义了从低到高的六级严重度见 base/log/logging.goSeverity 常量值说明TraceLevel1跟踪DebugLevel2调试InfoLevel3信息默认级别WarningLevel4警告ErrorLevel5错误CriticalLevel6严重代码中通过atomic存储当前级别提供GetLogLevel()/SetLogLevel()进行读取与热切换见 base/log/logging.go并把日志级别映射到标准库log/slog的 Level见toSLogLevel()。README 还提到可以使用 flags 按源文件粒度调整日志级别——这意味着你可以针对某个具体的.go文件单独控制其日志详细程度这在排查问题时非常有用。modules多阶段、依赖感知的启动流程modules组件负责把各个包组织成模块参与多阶段的启动与协调关停。注册一个模块只需要三样东西名称/key、prep()、start()和stop()函数。README 给出了完整的模块启动阶段表它定义了每个阶段哪些资源已经可用、模块应该做什么阶段可用资源模块职责init()flags、config、logging、dependencies均不可用用标准库flag注册 flags注册模块module.prep()flags、config、logging、dependencies响应 flags注册配置变量出错则返回错误返回ErrCleanExit表示干净、成功的退出例如程序只打印了版本号module.start()flags、config、logging、dependencies全部可用启动 tasks 和 workers启动阶段不要记录日志错误而是把它们 return 出来module.stop()flags、config、logging、dependencies全部可用停止所有工作如 goroutine同样不要记录日志错误而是 return 出来可以看到依赖dependencies要到start()阶段才可用这是依赖感知dependency aware启动的关键init→prep逐个就绪start时各模块的依赖已经齐备。模块还可以启动 tasks 和 workers这些任务会集成进模块系统为将来的洞察与更细粒度控制留出接口。源码结构提示在本文所检视的仓库版本中README 所述模块化启动理念的落地实现已经演进为 base/runtime/module.go提供Register、InjectAsDatabase等模块级 API 与DefaultRegistry与 service/mgr负责 worker/task 管理如mgr.New(Runtime)与mgr.WorkerCtx的组合。runtime模块在启动时会向数据库注册一个名为 runtime 的存储并把注册表注入其中。configJSON 字符串存储 三层优先级 函数式读取config组件的实现位于 base/config它的存储方式很特别配置以 JSON 字符串形式存放。听起来有点怪但非常实用——它让配置序列化、传输、持久化都变得统一简单。三层配置优先级配置分为三层按优先级从高到低用户配置user configuration——最高优先默认配置default configuration注册配置变量时提供的 fallback 值——最低优先。函数式读取又快又省心使用配置变量的核心方式是用GetAs*系列函数拿到一个配置函数之后每次都直接调用这个函数读取当前值。这个函数每次调用都会检查配置变量是否仍是最新如果没变读取路径极快如果变了它会重新拉取当前值——拉取虽然要花一点点时间但不会频繁发生。README 给出了字符串配置的完整示例// This is how you would get a string config variable function. myVar : GetAsString(my_config_var, default) // You then use myVar() directly every time, except when you must guarantee the same value between two calls if myVar() ! default { log.Infof(my_config_var is set to %s, myVar()) } // no error handling needed! :)无需错误处理——这是函数式读取带来的最大便利调用方永远拿得到一个值取值失败只会回退到 fallback。从 base/config/get.go 源码可以看到底层实现getValueCache()先查option的类型与注册状态然后按用户值 → 默认值 → fallback 值的顺序返回activeValue/activeDefaultValue/activeFallbackValue而GetAsString等函数用getValidityFlag()一个有效性标志做快速判断只有当标志失效时才重新走getValueCache并刷新本地缓存值。这正是未变化时极快、变化后重取的来源。config提供的读取函数家族见 base/config/get.go函数返回类型说明GetAsString(name, fallback)func() string字符串配置GetAsStringArray(name, fallback)func() []string字符串数组配置GetAsInt(name, fallback)func() int64整数配置GetAsBool(name, fallback)func() bool布尔配置⚠️ 重要警告非线程安全README 特别强调这些配置变量函数极快但并非 thread/goroutine 安全如果需要并发安全读取请使用Concurrent包装器见 base/config/get-safe.go。info把版本与构建信息烙进二进制info组件让你把版本号、commit 哈希、构建时间等元信息直接存储进二进制文件实现在 base/info/version.go。如果你用build脚本构建程序它会自动设置构建信息这样任何时候都能查出一个二进制是何时、从哪个 commit 构建出来的。build脚本的工作方式从主机与 git 仓库提取信息然后调用go build并附加额外参数注入版本、commit、构建时间等。info的核心 API见 base/info/version.goinfo.Set(name, version, license)设置程序名、版本与许可证README 强调这应该是程序调用的第一件事info.GetInfo()返回完整的Info结构名称、版本、源码、构建时间、CGO、commit、commit time、dirty 标志等其中 commit/构建时间取自 Go 构建信息debug.ReadBuildInfo的vcs.revision、vcs.time、vcs.modified设置info.Version()/info.VersionNumber()返回版本字符串与纯版本号info.FullVersion()输出多行完整版本信息构建工具链、GOOS/GOARCH、commit、许可证info.CondensedVersion()输出一行精简但完整的版本串。源码中还有一套自动版本推导如果 git 仓库是 dirtyvcs.modified true且版本号未带 dev build 后缀会在版本后追加 dev build见 base/info/version.go 的init()。formatsvarint 与 dsd 数据编码formats提供两个顺手的数据编码库formats/varint这是对标准库encoding/binary的便捷包装因为项目里大量使用 varint变长整数编码包装后调用更简洁。formats/dsd依赖formats/varintDSD 全称Dynamically Structured Data动态结构化数据。简言之它是一个根据所给数据类型做出反应的通用 packer打包器struct 通常按 JSON 编码[]byte与string保持原样不做额外包装。这种看类型行事的编码策略让不同数据类型存进 k/v 数据存储时更简单、更高效——比如结构化记录走 JSON、原始字节直接透传节省了不必要的序列化开销。rng可喂养的 Fortuna CSPRNGrng组件提供一套基于 Fortuna CSPRNG 的随机数生成器base/rng。Fortuna 由 Bruce Schneier 与 Niels Ferguson 设计本实现由 Jochen Voss 编写并公开发布。这里只使用fortuna包中的 Generator生成器部分而喂养feeding系统是自行实现的、可配置的并且以效率为优先考量。从 base/rng/rng.go 源码看生成器支持两种底层密码算法通过rngCipher变量选择取值算法aes默认AESserpentSerpent初始化时用fortuna.NewGenerator(newCipher)创建生成器随后异步从操作系统读取熵并调用rng.Reseed(osEntropy)完成首次播种。除了可以自己喂养 RNG它还内置两个默认的 feeder见 base/rng/osfeeder.go 与 base/rng/tickfeeder.goOS feeder启动时从crypto/rand读取种子之后周期性从crypto/rand重新播种tickfeeder一个非常简单的 feeder用 goroutine 从 Go 内部调度器提取熵适合在**高负载under load**场景下使用。这套设计把熵的采集与随机数生成解耦生成器保持 Fortuna 的密码学强度喂养策略则按场景灵活配置。database带 hooks、可同步、多后端 bucketed 数据库注README 中database与下一节api的正文均标注为 introduction to be written待撰写以下内容根据当前仓库 base/database 与 base/api 的源码结构整理帮助读者理解这两个组件的实际形态。README 给出的定位是智能且可同步的数据库带 hooks可与 struct 轻松集成使用不同后端的 buckets桶。从源码结构看该数据库包含以下关键部分记录层recordbase/database/record 定义了记录模型base、key、meta、wrappermeta 通过 gencode 生成支持高效的元数据编解码访问器accessorbase/database/accessor 提供 struct、JSON 字符串、JSON 字节三种访问方式accessor-struct.go即与 struct 轻松集成的实现查询querybase/database/query 提供一套查询 DSL含 AND/OR/NOT 条件、字符串/整数/浮点/布尔/正则/切片条件等见 base/database/query/condition-string.go 等文件与 base/database/query/README.mdhooksbase/database/hook.go 支持在数据变更时挂钩子回调订阅subscriptionbase/database/subscription.go 提供订阅机制为同步提供基础多后端存储buckets with different backendsbase/database/storage 下并列实现了多种存储后端后端实现文件Badgerbase/database/storage/badger/badger.gobboltbase/database/storage/bbolt/bbolt.gofstree文件系统树base/database/storage/fstree/fstree.gohashmap内存base/database/storage/hashmap/map.goSQLitebase/database/storage/sqlite/sqlite.gosinkhole丢弃base/database/storage/sinkhole/sinkhole.go数据库通过Database结构注册base/database/database.go包含名称、描述、存储类型与ShadowDelete选项被删除的记录是否保留到被 purge。从 base/runtime/module.go 可以看到注册示例database.Register(database.Database{Name: runtime, StorageType: injected, ...})随后InjectAsDatabase把注册表注入为数据库。api面向数据库的 websocket 接口api组件是数据库的 websocket 接口并可扩展自定义 http 处理器实现位于 base/api。从源码结构看客户端base/api/client/websocket.go 提供 websocket 客户端配套 base/api/client/message.go 的消息模型与 base/api/client/api.go 的 API 封装服务端base/api/router.go 负责路由base/api/endpoints.go 与 base/api/endpoints_config.go 等文件提供了内置端点如配置、debug、meta富响应base/api/enriched-response.go 实现了 enriched response富化响应机制让前端一次拿到更完整的上下文数据认证base/api/authentication.go 与 base/api/auth_wrapper.go 处理访问认证与包装。整体上api 层让数据库既能通过 websocket 被实时推送/订阅又能通过自定义 http handler 扩展业务接口——这正是 Portmaster 桌面 UI 与内核服务之间通信的基础形态。搭建主程序完整的 main 示例README 的最后给出了如果一切都用 modules 构建你的主程序应该长这样的完整示例。要点是用空导入blank import引入你需要的模块包让模块的init()完成自注册import ( os os/signal syscall github.com/safing/portmaster/base/info github.com/safing/portmaster/base/log github.com/safing/portmaster/base/modules // include packages here _ path/to/my/custom/module ) func main() { // Set Info info.Set(MySoftware, 1.0.0) // Start err : modules.Start() if err ! nil { if err modules.ErrCleanExit { os.Exit(0) } else { os.Exit(1) } } // Shutdown // catch interrupt for clean shutdown signalCh : make(chan os.Signal) signal.Notify( signalCh, os.Interrupt, syscall.SIGHUP, syscall.SIGINT, syscall.SIGTERM, syscall.SIGQUIT, ) select { case -signalCh: log.Warning(main: program was interrupted) modules.Shutdown() case -modules.ShuttingDown(): } }这段代码串联起前面所有概念info.Set(MySoftware, 1.0.0)第一件事设置程序元信息modules.Start()触发多阶段启动init → prep → start。返回modules.ErrCleanExit表示正常退出如只打印版本号以退出码 0 结束其他错误以退出码 1 结束信号捕获与协调关停监听os.Interrupt、SIGHUP、SIGINT、SIGTERM、SIGQUIT收到中断后调用modules.Shutdown()走stop()阶段有序关停同时用select等待modules.ShuttingDown()信号若模块自身先触发关停如某些致命条件主程序同样能干净收尾。小结与适用前提Portbase 把服务最需要的那批底层能力——极速日志、多阶段启动、动态配置、构建信息、编码库、CSPRNG、可同步数据库与 websocket API——集中在一处并让 Portmaster 与 Gate17 共享同一套地基。本文所述 API 与源码证据均来自当前仓库base/log/logging.go、base/config/get.go、base/info/version.go、base/rng/rng.go、base/database、base/api 等其中modules包的模块化启动理念在当前仓库版本中已由 base/runtime/module.go 与 service/mgr 承接落地。需要再次提醒的适用前提README 明确指出 Portbase 是为 Portmaster 与 Gate17 量身打造、相当贴合自身需求的库并不是为所有人准备的——如果你需要它没有的能力最好的路径是先提 issue 沟通或 fork 后自行扩展。使用config的函数式读取时务必留意其非线程安全的特性并发场景下请使用Concurrent包装器。赞分享网络安全【免费下载链接】portmaster Love Freedom - ❌ Block Mass Surveillance项目地址https://gitcode.com/gh_mirrors/po/portmaster点击查看免费下载相关推荐Cherry Studio 主进程 Core 基础设施解析应用级架构、启动三阶段与核心模块Cherry Studio 主进程 Core 基础设施解析应用级架构、启动三阶段与核心模块 Cherry Studio 的 v2 主进程将与业务无关的应用级人工智能大模型AI 应用交互助手本地部署Orchard Core Indexing 模块实战指南基于 Append-Only 任务日志的多提供者索引基础设施Orchard Core Indexing 模块实战指南基于 Append Only 任务日志的多提供者索引基础设施 本文以 Orchard Core 的 OCMS后端Web框架Mac Mouse Fix 完整指南4 个核心功能让普通鼠标在 Mac 上顺滑如初Mac Mouse Fix 完整指南4 个核心功能让普通鼠标在 Mac 上顺滑如初 你肯定经历过这种瞬间拿一支普通鼠标接上 Mac拨一下滚轮页面跳一格、桌面应用系统编程上一篇Visual C运行库一体化安装包Windows系统终极兼容性解决方案下一篇ollama-python 入门在 Django 应用中接入本地大模型创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考