Zany🥝

DeerFlow 2.0使用指南

2026-10-22T16:00:00.000Z

1、DeerFlow 2.0 是什么

DeerFlow 是字节跳动开源的智能体运行系统。它将模型、工具、子智能体、文件系统和记忆等能力组织起来，用于完成资料研究、内容整理、代码与文件处理等多步骤任务。

官方将 2.0 定位为 Super Agent Harness，可以理解为让智能体实际开展工作的运行环境。模型负责理解和决策，DeerFlow 提供执行任务所需的基础设施。

DeerFlow 2.0 是一次完整重写，旧版代码保留在 1.x 分支。 查找教程时，需要先确认教程针对的分支，避免把旧版配置复制进当前项目。官方项目说明。

本文按 2026-10-23 查阅的官方 main 分支文档整理。2.0 是本文讨论的产品架构，具体命令、配置项与界面仍应以下载的提交版本为准。本文仅记录使用方法，没有安装或启动 DeerFlow。

2、先理解几个核心概念

概念	主要职责	理解方式
Model	理解任务、生成计划、决定工具调用	智能体使用的推理与生成能力
Lead Agent	接收任务、协调工具与子任务	主执行者
Subagent	接收被拆分的任务并返回结果	分工处理的执行者
Tool	执行具体动作	搜索、读取文件、运行代码等操作
Skill	描述某类任务的流程与方法	可以复用的工作说明
Sandbox	提供文件和代码执行环境	完成实际操作的工作空间
Memory	保存适合跨会话使用的信息	长期偏好与上下文

一个典型任务可以按下面的过程理解：

用户描述目标
    → 主智能体理解任务
    → 按需要规划、调用工具或委派子任务
    → 在工作空间读取资料、处理文件
    → 整理结果并交付文件或回答

这是便于理解的流程，不代表每次请求都会经过所有步骤。简单问答不一定需要沙箱，复杂研究也不一定需要同时启动很多子智能体。后端组件说明。

3、项目由哪些部分组成

官方项目包含 Web 界面、后端 Gateway、智能体运行时以及可选执行组件。

位置	主要内容
`frontend/`	基于 Next.js 的 Web 界面
`backend/`	Gateway、智能体运行逻辑与相关模块
`skills/`	技能资源
`docker/`	容器编排、镜像及代理配置
`config.example.yaml`	主配置模板
`extensions_config.example.json`	扩展配置模板
`Makefile`	配置、安装、启动、停止与诊断入口

当前官方架构通过 Nginx 提供统一入口：网页请求进入前端，/api/* 进入 Gateway，/api/langgraph/* 提供兼容的智能体交互接口。默认访问端口是 2026。后端架构与路由。

初次使用可以从统一入口访问，先确认完整链路能正常工作，再考虑单独调试内部服务。

4、准备运行环境

4.1、两种启动方式

方式	特点	需要准备
Docker 开发环境	通过容器组织服务，适合先体验与调试	Docker、Compose、仓库脚本所需工具
本地开发环境	便于直接调试前后端代码	Node.js、pnpm、uv、nginx 等

当前 Docker 开发配置要求 Docker Compose v2.24 或更新版本。本地开发文档列出的 Node.js 要求为 22+，Python 环境与依赖按仓库的项目配置和锁文件准备。

官方开发环境资源建议以 4 核、8 GB 内存作为起步参考，较重的任务可以从 8 核、16 GB 内存评估。这是运行应用与容器的参考，不包含自行部署本地大模型所需的额外资源。开发环境指南。

Windows 下执行 make 前，需要确认 Make 可用；当前 Makefile 的 Windows 路径会通过 Git Bash 运行相关 Shell 脚本。Docker 方式还需要确认 Docker Desktop 已启动。官方 Makefile。

4.2、获取代码并生成配置

首次使用时，在准备存放项目的位置执行：

1
2
3

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make config

make config 用于生成本地配置。已有配置的项目跳过这一步，避免把初始化当成日常启动流程。

官方也提供 make setup 交互式配置向导；本文使用手动配置方式说明各部分作用。执行命令前，确认当前目录是 DeerFlow 仓库根目录。官方安装流程。

5、配置模型

5.1、模型配置需要哪些信息

至少准备模型名称、调用凭证和正确的服务地址。模型还需要能够完成所选任务使用的工具调用；普通文本对话可用，不代表完整的智能体流程一定可用。

下面是使用 OpenAI 兼容协议的配置片段，用于说明字段含义。把它合并到生成的 config.yaml 的 models 列表中，保留其余配置，不要重复声明两个 models 键。

models:
  - name: my-agent-model
    display_name: 自定义任务模型
    use: langchain_openai:ChatOpenAI
    model: replace-with-provider-model-id
    base_url: https://api.example.com/v1
    api_key: $MODEL_API_KEY
    max_tokens: 4096
    supports_vision: false

其中 name 是内部标识，model 是供应商实际接受的模型 ID，base_url 是对应 API 根地址。示例域名与模型 ID 都是占位值，需要替换。max_tokens 是单次调用的输出限制，不是整个任务的总预算。

use 决定适配器，模型特有的推理参数应参考对应示例；不能仅靠设置一个能力标记，就让不支持该功能的模型获得相应能力。模型配置指南。

5.2、环境变量放在哪里

上面的 $MODEL_API_KEY 表示从环境变量读取凭证。

对于官方 Docker 开发编排，Gateway 会读取仓库根目录的 .env。可以在该文件中加入自己的变量：

1	MODEL_API_KEY=replace_with_your_api_key

前端还有独立的 frontend/.env，两者用途不同。模型服务凭证应进入真正运行后端的环境；如果采用其他部署方式，需要核对对应进程或容器如何接收环境变量。Docker 开发编排配置。

凭证只保存在本地或部署环境中，不写入文章、截图和公开仓库。变更环境变量后，需要让对应服务重新加载配置。

6、启动与停止服务

6.1、Docker 开发方式

完成配置后，在仓库根目录执行：

1 2	make docker-init make docker-start

docker-init 负责所选沙箱模式需要的初始化准备；docker-start 才是应用服务的启动入口。启动完成后访问 http://localhost:2026。

查看开发环境日志：

1	make docker-logs

日常停止开发容器：

1	make docker-stop

首次启动的耗时可能包含依赖安装、镜像构建和下载，应结合日志判断当前阶段。应用使用 Docker 部署与任务采用哪一种沙箱模式，是两个需要分别确认的配置。Docker 开发流程。

6.2、本地开发方式

本地运行时，可以先检查工具，再安装依赖并启动：

1
2
3

make check
make install
make dev

对应的本地服务停止命令为：

make stop

两种开发方式选择一种运行即可。端口已被另一套实例占用时，先确认正在运行的服务来源，再决定停止哪一套。

make clean 会删除本地运行数据与日志，可能涉及会话、上传文件、记忆等数据。 日常停止使用上面的停止命令，故障排查先查看日志与配置。命令定义。

7、怎样描述一个容易执行的任务

开始任务前，可以先把需求拆成四部分：目标、材料、约束、交付物。

部分	可以填写的内容
目标	希望最终完成什么
材料	提供哪些链接、附件或数据
约束	时间范围、技术版本、引用要求、允许的操作
交付物	Markdown 报告、表格、代码或其他文件

例如准备一篇技术文章：

请整理一份 DTM 分布式事务的学习报告。

材料：以 DTM 官方文档和官方示例仓库为主要来源。
范围：Saga、TCC、二阶段消息和子事务屏障。
要求：说明适用场景、关键前提和失败处理，区分事实与实践建议。
代码：展示 Go 接入结构，未运行的示例必须明确标注。
交付：输出一份中文 Markdown 文件，并在相关段落附来源链接。

这段提示词是本文的使用示例。它将资料范围和验收要求写清楚，便于检查产出，也便于任务中断后继续补充。

对于文件分析任务，还可以给出需要核对的列名、单位、缺失值处理方式，以及希望保留的原始数据。一次任务包含多个交付物时，明确各文件的名称和用途。

7.1、根据任务选择执行方式

简短的问题可以先直接询问；需要研究、比较、计算和生成文件时，再使用界面提供的规划或子任务能力。

我的实践思路是先用一个边界清晰的小任务验证模型和工具，再扩大到完整流程。把任务完成与否落实到交付物上，例如报告是否含来源、表格是否能打开、代码是否注明验证范围。

8、Skills 与 MCP 的区别

Skill 用来组织“这类任务应该怎么做”，Tool 用来执行具体动作，MCP 则可以为智能体接入外部工具与服务。

例如“技术文章整理”Skill 可以规定资料检索、版本核对和文章结构；搜索工具或 MCP 服务提供实际检索能力。只有工作说明而没有可用工具，无法自动获得对应的外部数据。

当前官方界面通过工作区的 Capability Center 管理 Skills 与插件等能力。安装或导入后，还需要确认该能力对当前任务可用。Skills 与工具说明。

8.1、一个自定义 Skill 的思路

下面是本文编写的 SKILL.md 内容示例，用于表达技术文章整理流程；它不是已经安装到 DeerFlow 的技能包。

---
name: technical-article-notes
description: "根据官方资料整理中文技术文章，保留版本信息、代码前提和来源。"
---

# 技术文章整理

1. 明确主题、目标读者与技术版本。
2. 优先阅读官方文档、源码和维护者提供的示例。
3. 记录关键结论及其来源，区分已核实内容和推断。
4. 按背景、概念、接入方式、常见问题组织文章。
5. 将配置中的真实凭证替换为明确的占位值。
6. 对代码标注运行条件和验证范围。
7. 交付 Markdown 文件，并检查标题、日期、链接与代码围栏。

可先将团队反复使用的写作规范整理成这种流程，再按当前版本的技能目录或导入功能接入。引用资源、辅助脚本和工具需求也需要随技能一起组织，不能仅凭一个名称假设依赖已经准备完成。

9、沙箱、文件与记忆如何理解

9.1、确认代码执行的位置

沙箱模式决定任务在哪里读取文件和执行代码。当前项目提供本地执行与基于容器的执行方式；本地模式中的命令可能直接作用于宿主环境，容器模式则需要核对镜像、挂载与执行范围。

应用本身在容器中启动，不等于所有业务工具都自动获得同样的隔离边界。准备启用命令执行前，应先确认实际选用的 Provider。沙箱配置说明。

9.2、工作文件与最终文件

官方后端为线程组织工作目录、上传文件和输出文件，并使用虚拟路径映射到对应存储位置。

例如任务内部出现的 /mnt/user-data/outputs 是执行环境中的输出路径，不应直接理解为 Windows 本机磁盘路径。查看交付物时，使用界面提供的文件入口，并确认实际下载的是最终版本。文件系统说明。

9.3、会话与长期记忆

会话用于保留本次任务的过程，文件用于保存材料与产物，长期记忆用于跨会话的适当上下文。它们不应被当成同一种数据。

在实践中，可以将长期写作偏好与临时任务要求分开表达。任务完成后仍需检查实际产物，不把“系统记住了偏好”当成这次输出已经符合要求的证据。

10、常见问题怎么排查

现象	可以优先检查
网页能打开，发送消息失败	Gateway 日志、模型配置、凭证与供应商返回结果
模型可以聊天，但任务不会调用工具	所选模型的工具调用能力、适配器和工具配置
容器内访问本机模型失败	`localhost` 的实际指向、容器网络及服务监听地址
搜索没有结果	搜索工具是否启用、相关凭证、网络和来源限制
文件处理失败	文件是否上传成功、执行环境依赖、沙箱路径和权限
页面长时间没有流式内容	后端是否仍在运行、网络连接、反向代理的流式转发
升级后提示配置过旧	当前模板版本与本地配置差异，先备份再合并

模型、搜索服务、浏览器和文件执行是不同链路。排查时可以分别验证，再组合成完整任务，避免仅凭网页状态推断后端已经就绪。

官方提供 make doctor 诊断入口，配置更新还提供 make config-upgrade。升级前保留本地配置与运行数据副本，再依据当前版本说明处理变更。诊断与升级命令、配置版本说明。

如果部署到服务器，应先确定访问人员、鉴权和沙箱边界，再开放相应入口。模型凭证、执行环境和普通静态网页承担的权限不同，访问控制需要跟着实际能力一起配置。官方部署说明。

11、在个人技术学习中的使用思路

结合自己的博客，可以先尝试三个边界明确的场景：

官方资料整理：围绕一个版本生成学习提纲，保留来源与待核实事项。
代码阅读辅助：提供一组源码文件，整理调用关系与设计问题，再人工核对。
文章发布前检查：检查术语、代码前提、引用链接与段落结构，最终由自己确认内容。

这些是本文提出的任务设计方式，不代表 DeerFlow 对每个任务都能自动给出正确结论。使用时保留任务输入、来源和最终文件，才能持续改进自己的工作流程。

本文仅完成文档整理与示例说明，未进行 DeerFlow 部署、模型调用或端到端验证。后续使用时可以继续查阅官方仓库、安装说明与配置模板。

DTM分布式事务使用总结

2026-10-21T16:00:00.000Z

1、为什么需要分布式事务

一次下单可能需要完成三件事：创建订单、扣减库存、扣减账户余额。

如果这些数据都在一个数据库中，并且能够通过同一个数据库事务操作，通常先使用本地事务即可。出现错误时，数据库负责回滚本次事务中的修改。

当订单、库存和账户拆成独立服务，各自维护数据库后，订单服务中的一次 Rollback 无法撤销另一个服务已经提交的数据。此时需要设计跨服务的一致性方案。

DTM 是一个用 Go 编写的分布式事务管理器，通过事务协调、分支调用和失败重试，帮助多个服务按选定的事务模式完成业务。它支持 HTTP、gRPC 等接入方式；本文围绕 HTTP 和 Go SDK 展开。DTM 官方文档、通信协议。

本文记录学习与接入思路，示例不代表本站已经引入 DTM。示例中的服务地址、业务路由和数据库连接都需要根据实际项目配置。

2、先认识几个角色

角色或标识	含义	下单示例
事务发起方	组织本次业务流程并提交事务	接收下单请求的应用服务
DTM Server	持久化协调状态，调度分支和重试	独立部署的协调服务
事务分支	参与全局事务的一项业务操作	扣库存、扣余额
本地事务	每个分支内部的数据原子操作	同时写库存流水与更新库存
GID	一次全局事务的标识	本次下单流程的事务编号
Branch ID	全局事务内的分支标识	库存分支、账户分支的编号
业务单号	业务系统自身的唯一标识	订单号 `order_id`

GID 和订单号的职责不同。GID 用于协调事务，订单号用于查询订单、业务去重和对账。建议建立两者的持久化关联，以便在调用超时后仍能定位原来的事务。

DTM 协调的是各个服务的操作流程，各个服务仍然负责自己的本地事务、库存约束、余额约束和业务状态流转。DTM 架构。

3、常见事务模式怎么选择

模式	基本做法	适合考虑的场景	主要设计成本
Saga	执行正向操作，失败后执行补偿	能接受中间状态、能够定义补偿的业务	编写补偿逻辑
TCC	Try 预留，Confirm 确认，Cancel 释放	需要先冻结库存或额度的业务	维护资源预留及三阶段接口
XA	使用数据库的分布式事务能力	数据库支持相应协议、锁竞争可控的业务	控制锁持有时间，核对数据库支持
二阶段消息	协调本地事务结果和后续分支执行	本地成功后，后续操作需要持续向前完成	设计可靠回查与幂等分支

实际选择时，先问业务三个问题：是否需要撤销已经完成的动作，是否允许处理中状态对外可见，是否能够提前预留资源。再结合并发量和数据库条件选择模式。官方模式选择说明。

这些模式对数据可见性的处理方式不同，不能仅凭“用了分布式事务”就假设任意跨服务查询都获得同一个一致性快照。读接口与业务状态也需要配合设计。分布式事务基础理论。

4、Saga：先执行，失败后补偿

4.1、正常流程与补偿流程

下面以两个分支说明过程：

正常流程：
提交 Saga → 扣减库存成功 → 扣减余额成功 → 全局事务成功

业务失败：
提交 Saga → 扣减库存成功 → 扣减余额明确失败
         → 协调补偿 → 恢复库存 → 全局事务回滚完成

每个正向操作都需要明确对应的补偿语义：库存扣减对应恢复本次扣减数量，账户扣款对应撤销本次扣款。补偿通常需要参考原业务流水，不能简单把数据恢复成某个旧快照，否则可能覆盖其他并发业务的正常修改。

Saga 的补偿是新的业务操作。 正向操作的本地事务可能早已提交，因此它与数据库撤销未提交事务的 Rollback 不同。Saga 官方说明。

4.2、超时不代表没有执行

假设账户服务已经扣款并提交，但返回响应时网络断开。协调方看到的是超时，账户服务实际已经完成了业务。

因此，分支可能收到重复请求；结果不确定的分支也需要具备相应的补偿处理能力。业务接口必须围绕“请求可能重复、结果可能暂时未知”来设计，而不能依赖一次 HTTP 请求只发生一次。

对于发短信、发邮件、调用外部支付平台等动作，需要单独分析可撤销性和对方的幂等机制。不要把它们当成能够跟本地 SQL 一起回滚的操作。

5、TCC：先预留，再确认或释放

TCC 将业务拆成三个阶段：

阶段	库存示例	账户示例
Try	检查可用库存并冻结本次购买数量	检查可用余额并冻结本次金额
Confirm	将冻结库存转为正式销售消耗	将冻结金额转为实际扣款
Cancel	解除本次库存冻结	解除本次资金冻结

Try 阶段应完成必要的约束检查和资源预留。Confirm、Cancel 则围绕已经预留的资源完成收尾；如果到 Confirm 才检查是否还有库存，预留就失去了意义。

例如可以将资源分为“可用”和“冻结”两部分，另外保存每笔业务的预留记录。读取可用余额、取消预留、执行确认时，都应遵循同一套状态规则，避免其他接口绕过冻结限制。

TCC 的 Confirm、Cancel，以及 Saga 的补偿操作，都需要设计为在临时故障消除后能够最终完成。出现持续业务冲突时，应修复数据或逻辑，单纯增加重试次数并不能解决问题。最终成功的设计要求。

6、二阶段消息：保证后续操作继续完成

有些业务不适合“失败后撤销”，而是希望在本地操作成功后，让后续任务可靠地执行下去。

例如本地确认订单后，异步生成一份可重建的统计记录。统计服务临时不可用时，可以稍后补做，无须取消已经确认的订单。

这里的难点是两个动作之间的空隙：

1	提交本地数据库事务 → 进程退出 → 没有通知下游

把代码写成“先提交数据库，再调用下游”无法消除这个空隙。DTM 的二阶段消息通过准备、提交和本地事务结果回查等机制协调这两个阶段；接入时应使用对应 SDK 流程，并持久化可供回查的本地结果。二阶段消息示例。

回查应依据本地事务的可靠记录判断结果，不能因为临时查询失败就判断“业务没有发生”，也不能仅凭进程内存中的一个变量判断是否已经提交。

同样可以考虑本地消息表（Outbox）：把业务数据和待发送事件放进同一个本地事务，再由后台任务投递，消费者负责去重。两者都需要完整设计失败恢复路径，具体选择取决于系统已有设施与维护成本。其他事务模式。

7、子事务屏障解决什么问题

7.1、重复、空补偿和悬挂

问题	发生过程	未处理时的影响
重复调用	操作成功后响应丢失，协调方再次请求	重复扣款或重复恢复库存
空补偿	正向操作没有执行，补偿先到达	凭空增加库存或余额
悬挂	补偿已处理，延迟的正向请求随后到达	已取消的业务重新生效

DTM 的子事务屏障利用本地持久化记录和唯一约束，对同一事务分支的重复、乱序操作进行控制。接入时将业务写操作放入屏障回调，并与屏障记录使用同一个本地数据库事务。异常与子事务屏障。

屏障表应使用与所选 DTM、SDK 版本匹配的官方建表脚本，并部署在能够与对应业务数据共同提交的数据库中。不要把协调服务的事务表与业务侧的屏障表混为一谈。

7.2、屏障不替代业务幂等

用户连续点击两次下单，如果每次都创建一个新的 GID，对 DTM 来说就是两次不同的事务。

业务侧仍需使用订单号、请求幂等键或唯一索引，保证同一次业务请求映射到已有订单及事务。幂等键命中后，还要校验请求参数一致，避免同一个键被用于不同商品或金额。

屏障也不会自动约束不经过它的写入路径。库存、账户等关键数据应统一写入规则，并通过数据库约束和业务流水保留可核对的依据。

8、Go 接入 Saga 的基本写法

8.1、依赖与地址

本文使用 github.com/dtm-labs/client/dtmcli 的 HTTP 客户端接口。官方客户端还提供 dtmgrpc 和 workflow；旧文章可能使用其他仓库路径，复制代码时需要先核对项目自己的 go.mod。官方 Go 客户端。

DTM 默认 HTTP 端口为 36789，gRPC 端口为 36790。HTTP SDK 常用的协调地址形如 http://127.0.0.1:36789/api/dtmsvr。协议说明。

服务端和客户端依赖应选择兼容的版本并固定，不在文章中把某个版本号当成永久适用的“最新版”。可先参考官方快速示例，再移入自己的项目。

8.2、提交两个分支

下面是应用服务中的提交函数，展示 Saga 的组织方式。前提是 DTM Server 和库存、账户回调接口已经部署，调用方已经持久化订单号与 GID 的关联；它不包含完整的业务服务实现。

package order

import (
"fmt"
"strings"

"github.com/dtm-labs/client/dtmcli"
)

type SagaConfig struct {
DTMServer     string
InventoryBase string
AccountBase   string
}

type OrderPayload struct {
OrderID     string `json:"order_id"`
UserID      int64  `json:"user_id"`
ProductID   int64  `json:"product_id"`
Quantity    int64  `json:"quantity"`
AmountCents int64  `json:"amount_cents"`
}

func SubmitOrder(cfg SagaConfig, gid string, req OrderPayload) error {
if gid == "" || req.OrderID == "" || req.UserID <= 0 ||
req.ProductID <= 0 || req.Quantity <= 0 || req.AmountCents <= 0 {
return fmt.Errorf("事务标识或订单参数不合法")
}
if cfg.DTMServer == "" || cfg.InventoryBase == "" || cfg.AccountBase == "" {
return fmt.Errorf("DTM 或业务回调地址未配置")
}

inventory := strings.TrimRight(cfg.InventoryBase, "/")
account := strings.TrimRight(cfg.AccountBase, "/")
saga := dtmcli.NewSaga(cfg.DTMServer, gid)
saga.Add(inventory+"/deduct", inventory+"/restore", req)
saga.Add(account+"/debit", account+"/refund", req)
if err := saga.Submit(); err != nil {
return fmt.Errorf("提交订单事务未获得成功响应，请核对原 GID %s: %w", gid, err)
}
return nil
}

金额使用整数分传递，价格应由服务端根据商品和订单计算。示例中的 AmountCents 是内部服务参数，不应直接信任浏览器传入的金额。

Add 声明正向与补偿地址，Submit 向协调服务提交事务。上述代码没有设置等待全局完成的选项，返回 nil 后应先向用户展示“处理中”，再通过业务状态查询获取结果。Saga 客户端实现。

如果提交请求超时，不能立刻生成新 GID 再扣一次款。应保留原订单和 GID，按状态查询及恢复流程处理，避免把结果未知当成确定失败。

8.3、业务分支接入屏障

分支接口收到 DTM 的回调参数后，可以使用以下封装进入本地事务。示例针对 PostgreSQL；db 是已经初始化的 *sql.DB，apply 是使用传入 tx 执行本次业务 SQL 的函数。

package branch

import (
"database/sql"
"net/url"

"github.com/dtm-labs/client/dtmcli"
)

func ApplyPostgresBranch(
db *sql.DB,
query url.Values,
apply func(tx *sql.Tx) error,
) error {
barrier, err := dtmcli.BarrierFromQuery(query)
if err != nil {
return err
}
barrier.DBType = "postgres"
return barrier.CallWithDB(db, apply)
}

接口层先校验请求，再传入回调 URL 的查询参数及业务函数。数据库驱动、屏障表、业务表和 HTTP 响应映射仍需在项目中配置。屏障负责提交或回滚该本地事务，业务回调不要自行调用 tx.Commit()。屏障 SDK 实现。

回调里的业务 SQL 必须使用参数 tx。如果在回调中转而调用另一个独立连接上的 db.Exec，屏障记录和业务修改就不再属于同一次提交。

接入 GoFrame 等 ORM 时，也需要确认数据库方言与事务适配方式，确保所有写入复用屏障管理的事务连接。仅仅在外面包一层函数，内部继续使用默认数据库连接，并不能获得正确的事务边界。

9、HTTP 分支响应不能只看 JSON 字段

按 DTM 的 HTTP 分支协议，下面几类结果有不同含义：

HTTP 状态码	含义	业务处理示例
`200`	操作成功	扣库存已提交，或重复请求已被正确处理
`409`	确定的业务失败	Saga 正向扣款时确认余额不足，且未扣款
`425`	操作仍在处理中	已受理的外部流程尚无最终结果
其他错误，如 `500`	临时故障	数据库暂时不可用，需要重试

因此不能让全局响应中间件把所有分支结果都包装成 HTTP 200，再仅在 JSON 中写 code: 500。这可能让协调方误判业务已经成功。具体映射需与所使用的服务端版本保持一致。DTM 分支结果协议。

同样不要把数据库超时、连接失败都映射成 409。这些情况不一定是确定的业务拒绝，应保留重试或核对结果的空间。

补偿、TCC Confirm/Cancel、二阶段消息的后续分支属于需要最终完成的操作。它们遇到临时故障时应返回可重试结果；若存在永久无法完成的业务条件，需要重新设计流程，不能简单用 409 结束处理。

10、事务状态如何展示给用户

推荐在业务表中维护自己的处理状态，例如订单的 processing、completed、cancelled，并保留 order_id、GID 和必要的失败原因。这些名称是业务设计示例，不是 DTM 内部状态枚举。

客户端提交请求后可以获得订单号，展示“正在处理”，再查询业务状态。页面刷新后仍然可以通过订单号恢复展示，不依赖某次 HTTP 连接一直存在。

业务的最终成功状态必须在核对全局事务结果及业务数据后更新。不要因为库存分支完成就提前标记整笔订单成功，也不要仅凭浏览器超时就把订单取消。

查询或对账读取到过渡状态时，使用状态条件更新防止覆盖较新的终态。对于长时间未完成的事务，应提供可追踪的记录和人工处理入口。

11、部署与故障恢复要点

11.1、区分两类数据库

协调服务的存储用于保存全局事务及调度状态；业务数据库保存订单、库存、账户和相应屏障记录。两者承担的职责不同，不能只创建协调服务的表，就认为业务分支已经获得幂等保障。

实际部署应按所选版本的官方配置初始化存储、设置持久化和备份，并验证协调服务重启后的恢复流程。DTM 服务端仓库。

11.2、回调地址必须从 DTM 所在网络可达

提交给 DTM 的分支地址由协调服务访问。如果 DTM 运行在容器内，127.0.0.1 通常指向该容器自身；开发机上能访问的地址，不一定是容器或另一台服务器能访问的地址。

建议把协调地址与各业务回调地址分别配置。生产环境还应限制回调接口的访问来源，配置服务间认证，避免普通公网请求直接触发扣款或退款分支。

11.3、重试需要配合监控

网络短暂中断可以靠重试恢复，但代码错误、错误的补偿金额或业务数据损坏不会因为重试就自动消失。

可以重点监控全局事务处理时长、分支重试次数、持续失败的补偿操作，以及业务账目是否一致。告警阈值按实际业务时效设置，日志中保留订单号、GID、Branch ID 和操作类型，便于跨服务追踪。

恢复或人工修复前先确认原事务状态。不要直接删除屏障记录来“放开重试”，否则曾经成功的操作可能再次修改数据。

12、接入时容易踩的坑

现象	常见原因	改进方向
同一订单重复扣款	每次重试都创建新的事务	持久化业务幂等键、订单号与 GID 的关联
补偿多次增加库存	补偿接口缺少重复与空补偿控制	正向、补偿都接入一致的屏障机制
屏障记录成功但业务没完成	业务写入使用了独立事务	统一使用屏障回调中的事务连接
服务报告成功，协调结果异常	全局中间件覆盖了 HTTP 状态	为 DTM 分支单独配置协议响应
一直重试但无法结束	临时错误和永久业务冲突未区分	修复业务条件，完善告警与对账
容器内回调失败	分支 URL 使用了错误的本机地址	从协调服务所在网络核对连通性
通知、外部扣款重复执行	将外部调用当成本地 SQL 的一部分	使用外部幂等键、可靠事件及结果查询

这些问题需要结合数据库约束、业务状态机和恢复流程一起处理。DTM 能承担协调和重试，正确的资源变更与补偿语义仍由业务代码保证。

13、在自己的项目中如何逐步使用

学习时可以先构造两个独立业务服务，实现 Saga 正向操作和补偿，再接入屏障，逐步观察重复调用、明确失败、响应丢失和服务重启后的行为。

进入实际项目之前，应专门验证提交超时后使用原 GID 恢复、补偿先于正向到达、同一分支并发重复请求，以及业务事务提交后进程退出等场景。本文代码用于说明接入结构，未进行服务部署或端到端运行验证。

对于当前博客，评论与留言主要是单库创建和分页查询，优先使用本地事务即可。数据库写入后让缓存失效的逻辑，也应先按访问规模完善重试或可靠事件机制；等出现明确的跨服务一致性需求，再评估引入 DTM 的收益和维护成本。

DToken-Go认证与权限管理使用指南

2026-10-21T16:00:00.000Z

1、DToken-Go 能解决什么问题

在后台管理系统、用户中心或开放平台中，完成账号密码校验之后，通常还需要签发 Token、保存登录状态、校验接口权限，以及处理退出登录、多设备登录和账号封禁等问题。

DToken-Go 将这些能力组织为可以按需接入的 Go 模块，提供登录认证、Session、角色与权限、终端管理，以及 Refresh Token、SSO、OAuth2 等扩展能力。

认证用于确认当前是谁，授权用于判断当前账号能做什么。 两者都需要服务端执行，不能只靠前端隐藏按钮或菜单。

本文按项目文档及本地源码副本（提交 91e4df7）整理基础用法，主要介绍默认核心包和 GoFrame 集成。实际接入时应以所选版本的源码与 go.mod 为准；本文没有为本站安装依赖或启动示例服务。

2、模块结构与安装方式

2.1、按用途选择模块

该仓库使用多模块结构，不是所有代码都位于同一个 Go Module 中。

模块	用途
`defaults`	组装默认存储、编码器、Token 生成器等组件
`dtoken`	对外提供登录、退出、权限等通用 API
`core`	配置、Manager、组件接口及核心实现
`integrations/gf`	GoFrame 上下文、中间件与 API 导出
`integrations/gin`	Gin 框架集成
`com/storage/redis`	使用 Redis 保存认证相关状态
`sso`	按需接入的单点登录模块

独立使用认证核心时，可以安装：

1 2	go get github.com/Zany2/dtoken-go/defaults go get github.com/Zany2/dtoken-go/dtoken

已经使用 GoFrame 的项目，可以直接选择对应集成包：

1	go get github.com/Zany2/dtoken-go/integrations/gf

需要 Redis 存储时，再引入：

1	go get github.com/Zany2/dtoken-go/com/storage/redis

以上命令用于说明模块路径。正式项目应固定经过验证的兼容版本，并提交 go.mod、go.sum。仓库中的 go.work 用于仓库自身的多模块开发，业务项目不需要直接复制它。项目安装说明。

2.2、不要混用不同层级的 API

初次使用可以先选定一种方式：普通 Go 程序使用 defaults 和 dtoken，GoFrame 应用使用别名为 gfdt 的框架集成包。

全局函数、实例门面和请求上下文 API 的参数形式不完全相同。例如全局的 dtoken.Logout(ctx, token) 需要显式 Token，而请求上下文中的 dCtx.Auth().Logout(ctx) 可以从当前请求解析 Token。

3、一个最小的登录与退出示例

默认 Builder 使用内存存储，适合先理解调用流程。下面是一个控制台示例，不包含 HTTP 登录接口，也不执行账号密码校验。

package main

import (
"context"
"fmt"
"log"

"github.com/Zany2/dtoken-go/defaults"
"github.com/Zany2/dtoken-go/dtoken"
)

func main() {
if err := run(); err != nil {
log.Fatal(err)
}
}

func run() error {
mgr, err := defaults.NewBuilder().
TokenName("Authorization").
Timeout(7200).
AutoRenew(false).
IsShare(false).
IsPrintBanner(false).
Build()
if err != nil {
return fmt.Errorf("初始化认证管理器: %w", err)
}
dtoken.SetManager(mgr)
defer dtoken.DeleteAllManager()

ctx := context.Background()
// 演示假定业务层已经完成身份校验。
token, err := dtoken.Login(ctx, "user-1001", "web", "browser-demo")
if err != nil {
return fmt.Errorf("签发登录凭证: %w", err)
}
if err := dtoken.CheckLogin(ctx, token); err != nil {
return err
}
loginID, err := dtoken.GetLoginID(ctx, token)
if err != nil {
return err
}
fmt.Println("当前登录账号:", loginID)

if err := dtoken.AddPermissions(ctx, loginID, []string{"article:read"}); err != nil {
return err
}
fmt.Println("可以读取文章:", dtoken.HasPermission(ctx, loginID, "article:read"))

if err := dtoken.Logout(ctx, token); err != nil {
return err
}
fmt.Println("退出后仍然登录:", dtoken.IsLogin(ctx, token))
return nil
}

示例依次完成初始化、注册 Manager、登录、查询身份、添加演示权限和退出。AutoRenew(false) 用于先观察固定 TTL；需要活跃续期时再按业务要求开启。

内存存储跟随进程存在，进程重启后不能指望保留登录态，多实例之间也不会自动共享这些数据。登录认证指南。

4、真实的登录接口应该怎样组织

Login(ctx, loginID) 的含义是为一个已经确认的身份建立登录态。它不会自动查询你的用户表，也不会验证用户填写的密码。

真实流程可以组织为：

接收用户名与密码
    → 校验输入并查询用户
    → 校验密码哈希或验证码
    → 得到数据库中的稳定用户 ID
    → 调用 DToken-Go 建立登录态
    → 将 Token 返回给客户端

不要把浏览器提交的 user_id 直接交给 Login，也不要照搬演示程序，为所有登录用户赋予 admin 角色。用户 ID、角色与权限都应来自服务端可信的业务数据。

设备类型可以使用 web、app 等业务约定；设备 ID 用于区分具体终端。客户端提供的设备标识属于管理辅助信息，不应单独作为身份认证依据。

当配置 TokenName("Authorization") 并开启 Header 读取时，客户端可以按以下形式携带登录凭证：

1
2
3

GET /api/me HTTP/1.1
Host: daixiaokang.com
Authorization: Bearer <登录接口返回的 Token>

这里的域名和路由仅说明请求结构，不代表本站已经提供该认证接口。Token 不放入 URL，不写入普通访问日志；服务端接收来源应与客户端发送方式保持一致。

5、有效期、活跃超时和续期

配置	含义	示例值
`Timeout`	本次签发或续期后的 Token 有效时长	`7200`，两小时
`ActiveTimeout`	允许的最长不活跃时长	`1800`，半小时
`AutoRenew`	登录校验时是否按规则触发自动续期	`true` 或 `false`
`RenewMaxRefresh`	剩余 TTL 达到该阈值时才考虑续期	`3600`，一小时
`RenewInterval`	同一个 Token 的最小自动续期间隔	`60`，一分钟
`RefreshTokenTimeout`	刷新凭证的有效时长	`2592000`，三十天

Builder 中这些数值时间配置的单位是秒，不要直接把 time.Hour 的纳秒数强制转换后传入。对支持 Duration 的配置，也可以使用 TimeoutDuration(2 * time.Hour) 等明确时长的入口。

开启自动续期后，Timeout 不能理解为“从首次登录起最多只能在线两小时”。持续活跃并成功续期的登录态可能继续存在；若业务需要强制重新认证，应另行设计最长登录时长策略。

配置之间还有关系：启用自动续期时不能把 Timeout 设成永不过期；续期阈值不能大于有效期，最小续期间隔也应小于有效期及已启用的活跃超时。初始化时检查 Build() 的错误，能及早发现不合法组合。配置指南。

6、角色与权限怎么使用

6.1、区分角色与权限

角色可以表达人员分组，例如 editor、admin；权限可以表达具体动作，例如 article:read、article:publish。

给账号添加角色，并不意味着框架会自动从业务数据库解析这个角色拥有的所有权限。角色到权限的映射需要由业务系统提供，或通过动态权限来源接入。

下面的函数适合在可信的服务端授权流程中调用，演示给已有登录会话添加角色和权限：

func GrantEditorAccess(ctx context.Context, loginID string) error {
if err := dtoken.AddRoles(ctx, loginID, []string{"editor"}); err != nil {
return err
}
return dtoken.AddPermissions(ctx, loginID, []string{
"article:read",
"article:publish",
})
}

这是函数片段，依赖 context 与 dtoken 导入。正式角色分配还应写入业务权限表，并处理权限变更后的缓存或 Session 同步；不要把演示授权函数直接暴露为任意用户可调用的接口。

6.2、接口中先检查登录，再检查权限

已经持有 Token 的服务端代码，可以使用：

func CheckArticlePublish(ctx context.Context, token string) error {
if err := dtoken.CheckLogin(ctx, token); err != nil {
return err
}
return dtoken.CheckPermissionByToken(ctx, token, "article:publish")
}

Has* 适合只需要布尔值的判断；接口层希望保留拒绝或存储异常的具体原因时，可以使用返回错误的 Check*。检查某个权限不等于检查某条数据的归属，编辑文章时仍需判断作者、租户等业务条件。

多个权限还可以表达 AND、OR 关系，分别表示全部满足或至少满足一个。权限字符串支持分段通配符，例如 article:*；命名时保持分隔符与层级一致，不要把一个宽泛通配符当成所有接口都需要的默认权限。权限管理指南。

7、权限从数据库读取：AccessProvider

初步接入时可以把角色、权限放在 Session 中；如果业务已经有用户、角色和权限表，或者权限需要频繁调整，可以使用 AccessProvider 从业务系统解析。

Provider 能获得账号、认证体系和设备等上下文，业务可据此查询数据库或权限服务。使用时需要明确以下区别：

Provider 返回值	含义
`nil, nil`	本次不接管，允许继续使用 Session 权限数据
空切片、无错误	明确表示没有权限，不回退到 Session
非空权限列表	使用 Provider 返回的数据
错误	本次权限解析失败，应拒绝并按接口规则处理

尤其在权限撤销时，不能把“查到零条权限”误写成 nil, nil，否则可能继续使用旧的 Session 授权。动态查询也要设计超时、缓存失效和故障告警。AccessProvider 指南。

8、接入 Redis 存储

多实例部署时，应让相关实例使用一致的认证配置和共享存储。下面演示在初始化阶段从环境变量读取 Redis URL，创建存储并注册 Manager：

package authsetup

import (
"fmt"
"os"
"strings"

dtredis "github.com/Zany2/dtoken-go/com/storage/redis"
"github.com/Zany2/dtoken-go/defaults"
"github.com/Zany2/dtoken-go/dtoken"
)

func InitRedisAuth() error {
redisURL := strings.TrimSpace(os.Getenv("DTOKEN_REDIS_URL"))
if redisURL == "" {
return fmt.Errorf("未配置 DTOKEN_REDIS_URL")
}
storage, err := dtredis.NewStorage(redisURL)
if err != nil {
return fmt.Errorf("初始化认证存储失败: %w", err)
}
mgr, err := defaults.NewBuilder().
SetStorage(storage).
KeyPrefix("website:dev").
TokenName("Authorization").
Timeout(7200).
AutoRenew(false).
IsPrintBanner(false).
Build()
if err != nil {
_ = storage.Close()
return err
}
dtoken.SetManager(mgr)
return nil
}

例如本地无密码 Redis 的 URL 可以是 redis://127.0.0.1:6379/0。真实密码从环境配置读取，不写进文章或版本库；连接错误的详细内容留在受控日志中，不直接返回客户端。

KeyPrefix 用于区分项目或环境，生产部署应使用生产环境自己的前缀。Manager 初始化一次后供请求复用，不要在每个请求里创建 Redis 连接和 Manager。

上面的函数采用默认组件所有权，初始化成功后由应用关闭 Manager 时释放其持有的组件。多个 Manager 共用同一存储客户端时，需要按项目的组件所有权选项安排统一关闭；先停止新请求并排空正在执行的业务，再关闭认证组件。Redis 存储指南、组件生命周期说明。

9、在 GoFrame 中接入

9.1、先初始化框架 Manager

在 GoFrame 项目启动时，可以使用 gfdt.NewBuilder() 构建 Manager，再调用 gfdt.SetManager(mgr)。Builder 的返回值仍需检查错误；Redis 存储也可以通过 SetStorage 注入。

基础顺序如下：

1 2	加载配置 → 创建存储和 Manager → 注册 Manager → 注册请求上下文中间件 → 注册登录及受保护路由 → 启动服务

应用退出时，在 HTTP 请求排空后关闭 Manager。不要在普通控制器内调用全局清理函数。

9.2、路由与中间件示例

下面是路由注册函数。它依赖启动阶段已经注册的默认 Manager，并接收业务已经实现的登录处理器、文章处理器和认证错误处理器；它不是完整的启动程序。

package authroute

import (
"context"

gfdt "github.com/Zany2/dtoken-go/integrations/gf"
"github.com/gogf/gf/v2/net/ghttp"
)

func RegisterAuthRoutes(
s *ghttp.Server,
loginHandler ghttp.HandlerFunc,
articlesHandler ghttp.HandlerFunc,
authFail func(r *ghttp.Request, err error),
) {
ctx := context.Background()
failOption := gfdt.WithFailFunc(authFail)
s.Use(gfdt.RegisterDTokenContextMiddleware(ctx, failOption))

// 登录接口由业务层校验密码或验证码，不要求已有登录态。
s.Group("/api", func(group *ghttp.RouterGroup) {
group.POST("/login", loginHandler)
})

s.Group("/api", func(group *ghttp.RouterGroup) {
group.Middleware(gfdt.AuthMiddleware(ctx, failOption))
group.GET("/articles", gfdt.CheckPermissionMiddleware(
ctx, []string{"article:read"}, articlesHandler, authFail,
))
group.GET("/me", func(r *ghttp.Request) {
dCtx, ok := gfdt.GetDTokenContext(r)
if !ok {
authFail(r, gfdt.ErrNotLogin)
return
}
loginID, err := dCtx.Auth().GetLoginID(r.Context())
if err != nil {
authFail(r, err)
return
}
r.Response.WriteJson(map[string]string{"login_id": loginID})
})
})
}

上下文中间件用于接入请求上下文，不能把“已经注册上下文”理解为“所有接口已经要求登录”。AuthMiddleware 才在受保护路由上校验登录态，权限中间件继续检查对应业务权限。

authFail 应由业务统一实现：未登录或 Token 失效通常返回 HTTP 401，权限不足或账号受限返回 403，存储与服务内部故障返回适当的 5xx，详细错误写入服务端日志。返回后终止本次处理，避免继续执行业务。示例中的三个处理器都应传入有效函数。

项目还有动态路由授权入口 AccessMiddleware，可根据匹配的业务路由声明权限。接入初期先把固定路由的登录与权限关系理清，再集中管理规则，避免误把后台接口设置为公开接口。完整 GoFrame 示例、GoFrame 中间件实现。

10、刷新令牌与自动续期的区别

自动续期主要围绕当前仍有效的登录凭证延长 TTL；Refresh Token 则用于通过单独的刷新凭证换取新的令牌对。需要双令牌时，可以在身份校验成功后调用 LoginWithRefreshToken。

下面的函数片段展示调用顺序，假设 Manager 已初始化，loginID 来自可信的身份校验结果：

func RefreshExample(ctx context.Context, loginID string) error {
pair, err := dtoken.LoginWithRefreshToken(ctx, loginID, "web", "browser-demo")
if err != nil {
return err
}

// 真实项目由客户端保存刷新凭证，稍后向刷新接口提交。
nextPair, err := dtoken.RefreshToken(ctx, pair.RefreshToken)
if err != nil {
return err
}

// 演示结束时撤销最新的刷新凭证。
return dtoken.RevokeRefreshToken(ctx, nextPair.RefreshToken)
}

刷新会轮换凭证，客户端应保存新的令牌对，不继续使用旧的 Refresh Token。多个请求同时发现需要刷新时，应合并成一次刷新流程，避免并发消费同一旧凭证。

刷新接口不能被“必须持有有效 Access Token”的中间件挡住，否则访问令牌到期后反而无法刷新；它应单独校验 Refresh Token，并配合自己的限流与异常处理。当前项目的普通登录刷新与 OAuth2 刷新是不同入口，不要混用。Refresh Token 指南。

11、终端管理与多认证体系

11.1、退出、踢下线与顶下线

操作	主要用途
`Logout`	当前凭证正常退出
`Kickout`	管理端主动踢出，保留下线原因
`Replace`	登录替换场景，保留被顶下线原因
`LogoutByLoginID`	对指定账号的全部终端执行退出

选择操作时也要选择范围：当前 Token、账号、设备类型或某个设备。退出当前浏览器时，不应误调用账号全部终端退出。

IsConcurrent、IsShare、MaxLoginCount 等配置共同决定并发登录和 Token 复用策略。需要多个独立会话时，不要同时期待所有登录都共享同一个 Token；具体组合参考Session 与终端管理。

11.2、用户端与管理端隔离

同一个应用同时提供用户端和后台管理端时，可以通过 AuthType("user")、AuthType("admin") 注册不同的 Manager。

AuthType 参与认证数据的命名空间隔离，KeyPrefix 更适合区分项目或环境，两者职责不同。注册不同认证体系之后，登录、查询、退出和路由中间件都应选择对应体系。

尤其注意全局 Login 的可选参数顺序是设备类型、设备 ID、认证体系。Login(ctx, id, "web") 中的 web 是设备类型，不是认证体系；需要指定体系时应按完整参数位置传入，或使用项目提供的实例、选项式入口。多认证体系指南。

12、常见问题与接入建议

问题	排查方向
登录后调用接口仍然未登录	检查 Manager 注册、Token 来源、认证体系和请求头
本地正常，多实例部署后时好时坏	检查是否仍使用各进程独立的内存存储
添加了 `admin` 角色仍无文章权限	角色与具体权限的映射需要业务提供
修改数据库权限后接口权限未变化	检查 Session 权限、Provider 返回值与缓存失效策略
刷新一次成功，再用原凭证刷新失败	刷新凭证已轮换，客户端应保存最新令牌对
Builder 初始化失败	检查时间单位、续期约束和组件配置，不忽略错误
JWT 能解析但登录校验失败	仍需检查服务端登录态、封禁、会话与有效期

项目的 JWT 模式并不意味着完全无状态：Session、终端和权限等能力仍会使用服务端存储。需要 JWT 时应按对应指南配置自己的密钥，不能把客户端能够解析 Token 当成服务端认证通过。JWT 指南。

建议先跑通“身份校验 → 登录 → 受保护接口 → 退出”的基本流程，再接入数据库权限、Redis、多终端和双令牌。Nonce、Ticket、ShortKey、OAuth2 等可选能力按实际场景启用，SSO 则作为独立模块设计接入边界。

本文示例已按项目接口整理，用于说明使用方式；没有运行认证服务、连接 Redis 或进行端到端验证。完整行为和版本变化可继续查阅项目文档中心及示例目录。

GoFrame框架使用总结

2026-10-08T15:43:00.000Z

1、基本介绍

GoFrame 是一个面向 Go 项目开发的框架，除了 HTTP 服务，还提供配置、日志、校验、数据库访问等组件。学习时可以先围绕一个小接口，把请求接收、业务处理、数据库操作和响应返回串起来，再逐步理解其他模块。

本文以 GoFrame v2 为基础，整理开发中常用的写法和容易忽略的细节。查阅时官方文档处于 2.10.x 分支，实际项目仍应以自己的 go.mod 和 gf 工具版本为准，不直接混用 v1 的导入路径。

下面的留言示例用于讲解 GoFrame；当前博客的评论、留言后端使用 FastAPI，文章中的示例不代表本站已经迁移了后端框架。

2、创建项目与常用命令

安装 Go 和官方 gf 命令行工具后，先确认本机版本。CLI 的安装方式可以参考官方工具安装文档，项目依赖和 CLI 尽量使用相互匹配的版本。

go version
gf version

gf init gf-notes
cd gf-notes
go mod tidy
gf run main.go

gf init 创建脚手架项目；gf run main.go 会监视代码变化，重新编译并重启程序，适合开发阶段。它不是在原进程里替换代码，重启期间内存中的临时状态也会丢失。项目创建说明、自动编译说明。

其他常用命令：

命令	用途	使用时注意
`gf gen ctrl`	根据 API 定义生成控制器相关代码	生成后检查路由注册和待实现方法
`gf gen dao`	根据数据库表生成 DAO、DO、Entity	数据库要先有表，不会代替建表迁移
`gf gen service`	从符合规范的 logic 实现生成 service 接口	手工维护接口时注意工具覆盖规则
`go test ./...`	执行 Go 测试	依赖数据库的测试与纯函数测试分开组织
`go build -o bin/gf-notes .`	编译当前项目	Windows 可把输出名写成 `bin/gf-notes.exe`

生成代码前先阅读对应目录的文件头。标明由工具维护的文件，不适合直接塞入业务逻辑，否则下次生成可能被覆盖。DAO 生成文档、Service 生成文档。

3、项目目录应该怎么理解

官方脚手架中经常见到这些目录：

api/                    对外接口的请求、响应定义
internal/
  cmd/                  启动命令与路由组装
  controller/           将请求转换为业务调用和响应
  service/              业务接口定义
  logic/                业务接口的具体实现
  dao/                  数据访问对象
  model/
    do/                 数据操作模型
    entity/             数据表实体模型
manifest/config/        应用配置
resource/               静态资源
main.go                 程序入口

例如一个“发表留言”请求，可以按下面的顺序理解：

HTTP 请求
  → api：定义字段与基础校验
  → controller：组织输入、调用业务服务
  → service 接口 / logic 实现：执行业务规则
  → dao：访问数据库
  → controller：组装对外响应

service 在这套规范里主要是接口层，具体业务实现通常放在 logic。小演示可以直接在控制器里写逻辑；当多个入口需要复用同一套规则时，再抽到业务层更合适。官方工程目录设计。

我会按以下边界组织自己的代码：

API 对象只暴露接口确实需要的字段，不把数据库实体直接作为公开响应。
昵称整理、回复关系校验、状态控制等规则放在业务层，方便 HTTP、管理端和任务程序复用。
DAO 层不承包所有业务判断，避免出现“Service 只转发、DAO 装下所有逻辑”的情况。
使用生成式 Service 注册时，检查启动入口是否已经引入 logic 的注册包；生成了接口，不等于具体实现已经注册。

4、规范路由、参数校验与接口文档

规范路由把路径、请求方法和字段规则写进结构体，并用固定的处理函数签名接收请求。基础校验由框架完成，控制器处理校验后的请求。规范路由文档。

下面是一个独立的 main.go 演示。它只展示留言输入校验与统一响应，回显整理后的内容，不会保存到数据库。已有脚手架项目应把这些定义拆到对应目录，不要直接覆盖原入口。

package main

import (
"context"
"strings"

"github.com/gogf/gf/v2/errors/gcode"
"github.com/gogf/gf/v2/errors/gerror"
"github.com/gogf/gf/v2/frame/g"
"github.com/gogf/gf/v2/net/ghttp"
)

type MessagePreviewReq struct {
g.Meta   `path:"/messages/preview" method:"post" tags:"留言" summary:"校验留言内容"`
Nickname string `json:"nickname" v:"required|length:1,50" dc:"昵称"`
Content  string `json:"content" v:"required|length:1,2000" dc:"留言内容"`
}

type MessagePreviewRes struct {
Nickname string `json:"nickname"`
Content  string `json:"content"`
}

type MessageController struct{}

func (c *MessageController) Preview(ctx context.Context, req *MessagePreviewReq) (*MessagePreviewRes, error) {
nickname := strings.TrimSpace(req.Nickname)
content := strings.TrimSpace(req.Content)
if nickname == "" || content == "" {
return nil, gerror.NewCode(gcode.CodeValidationFailed, "昵称和内容不能只包含空白字符")
}
return &MessagePreviewRes{Nickname: nickname, Content: content}, nil
}

func main() {
s := g.Server()
s.SetAddr(":8199")
s.SetOpenApiPath("/api.json")
s.SetSwaggerPath("/swagger")
s.Group("/api", func(group *ghttp.RouterGroup) {
group.Middleware(ghttp.MiddlewareHandlerResponse)
group.Bind(new(MessageController))
})
s.Run()
}

这个例子的接口地址为 POST /api/messages/preview；OpenAPI JSON 位于 /api.json，Swagger 页面位于 /swagger。请求体示例：

{
  "nickname": "Zany",
  "content": "记录一下今天学到的内容。"
}

几个常用标签可以这样记：

标签	作用	示例
`g.Meta`	接口路径、方法、分组和说明	`path:"/messages" method:"get"`
`json`	JSON 字段名称	`json:"nickname"`
`v`	输入校验规则	`v:"required
`d`	参数默认值	`d:"1"`
`dc`	文档字段说明	`dc:"页码"`

required 建议放在组合校验规则的前面。字段必填、长度合法，不等于业务合法；例如回复目标是否存在、用户是否有权限，还需要业务层继续判断。修改接口涉及 0、false 或“未传字段”的区别时，可以使用指针字段表达可选输入。校验规则。

注册 MiddlewareHandlerResponse 后，处理函数通常返回 Res 和 error，由中间件组织结果。不要在同一个普通 JSON 接口里既手动写响应，又返回另一份结果。业务码也不等于 HTTP 状态码；正式项目需要明确两者的对应规则，并对数据库内部错误做脱敏。规范路由使用说明。

5、配置与数据库驱动

脚手架通常使用 manifest/config/config.yaml。以下为开发环境的配置形状，数据库账号是示例值：

server:
  address: ":8199"
  openapiPath: "/api.json"
  swaggerPath: "/swagger"

logger:
  path: "./logs"
  level: "all"
  stdout: true

database:
  default:
    link: "pgsql:app:replace_me@tcp(127.0.0.1:5432)/gf_notes"

第 4 节为了便于单文件演示，在代码里设置了 Server 参数。回到工程项目时，可以统一使用配置文件，避免配置值与硬编码各维护一份。

GoFrame v2 的数据库驱动需要单独引入。例如 PostgreSQL 使用以下驱动包，并在程序启动时完成导入注册；驱动版本应与项目采用的框架版本匹配。ORM 介绍、数据库配置格式。

1	import _ "github.com/gogf/gf/contrib/drivers/pgsql/v2"

配置组件可以通过 g.Cfg() 读取；Get 返回配置值和错误，MustGet 在读取失败时会触发 panic，因此关键业务路径应按需要选择错误处理方式。想用环境变量提供秘密信息时，要明确使用相应读取方法或配置适配逻辑，不要默认 YAML 中的任意 ${变量} 都会自动展开。配置读取方法。

生产数据库密码放在部署环境或受保护的配置中，文章、仓库和日志里只保留示例。切换数据库类型时，驱动、连接格式、SQL 方言和主键返回方式都需要一起检查。

6、数据库操作：先把查询边界写清楚

这一节的代码是业务函数片段，需要放入已配置 GoFrame 和 PostgreSQL 驱动的 Go 包中，并补齐对应 import。它们不属于上面的无数据库演示。

为了便于理解，约定演示表为 demo_messages，不是当前博客的生产表：

CREATE TABLE demo_messages (
    id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    nickname VARCHAR(50) NOT NULL,
    content TEXT NOT NULL,
    status SMALLINT NOT NULL DEFAULT 1,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP NULL
);

CREATE INDEX idx_demo_messages_public
    ON demo_messages (created_at DESC, id DESC)
    WHERE status = 1 AND deleted_at IS NULL;

建表 SQL 和后面的代码都只是文章示例，运行前应使用独立的演示数据库。gf gen dao 是“从已有表生成代码”，数据库表结构变更仍需维护迁移脚本。

6.1 创建：白名单组织写入字段

func CreateMessage(ctx context.Context, nickname, content string) error {
_, err := g.DB().Model("demo_messages").Ctx(ctx).Data(g.Map{
"nickname": nickname,
"content":  content,
"status":   1,
}).Insert()
return err
}

调用这个函数前要完成输入整理和业务校验。status 由服务端决定，不让访客通过请求体修改。客户端提交什么就整包写入数据库，很容易把内部字段也暴露成可写字段。

创建与更新最好明确区分；Save 涉及冲突时的插入或更新语义，不能一律当成“新增”使用。涉及返回自增 ID 时，应核对具体数据库驱动的支持方式，尤其不要把所有数据库都当成 MySQL 的 LastInsertId。写入保存文档。

6.2 查询：列表和总数使用同一组过滤条件

下面片段需导入 context、gerror、g 和 gtime：

type MessageItem struct {
ID        int64       `json:"id" orm:"id"`
Nickname  string      `json:"nickname" orm:"nickname"`
Content   string      `json:"content" orm:"content"`
CreatedAt *gtime.Time `json:"created_at" orm:"created_at"`
}

func ListMessages(ctx context.Context, page, size int) ([]MessageItem, int, error) {
if page < 1 || page > 10000 || size < 1 || size > 50 {
return nil, 0, gerror.New("分页参数不合法")
}
items := make([]MessageItem, 0)
var total int
err := g.DB().Model("demo_messages").Ctx(ctx).
Fields("id", "nickname", "content", "created_at").
Where("status", 1).
WhereNull("deleted_at").
OrderDesc("created_at").OrderDesc("id").
Page(page, size).
ScanAndCount(&items, &total, false)
if err != nil {
return nil, 0, err
}
return items, total, nil
}

ScanAndCount 用来组织列表和总数查询，但不代表它们被合并成一条 SQL，也不自动保证并发写入时两次查询看到相同快照。这里第三个参数传 false，表示计数不沿用 Fields 作为 COUNT 参数。ScanAndCount 文档。

公开列表需要始终带上状态和软删除条件。排序增加 id 作为相同创建时间下的确定顺序；深分页或持续新增的动态列表，可以考虑使用游标分页，而不是无限增大页码。

6.3 更新与软删除：带上明确条件

以下是软删除函数示例，需额外导入 gtime。调用前还要完成身份和权限校验：

func SoftDeleteMessage(ctx context.Context, id int64) error {
if id <= 0 {
return gerror.New("留言 ID 不合法")
}
result, err := g.DB().Model("demo_messages").Ctx(ctx).
Where("id", id).WhereNull("deleted_at").
Data(g.Map{"deleted_at": gtime.Now()}).Update()
if err != nil {
return err
}
affected, err := result.RowsAffected()
if err != nil {
return err
}
if affected == 0 {
return gerror.New("留言不存在或已经删除")
}
return nil
}

软删除仅改变记录状态，不会自动保证你写的每条查询都排除已删除数据。需要区分框架已配置的软删除规则与自己手动维护的字段，避免只加了 deleted_at，查询时却忘记过滤。

条件值交给 ORM 参数化处理；排序字段、表名等不能简单视为普通参数，动态排序应使用服务端白名单映射，不能直接拼接用户输入。ORM 使用说明。

7、事务与 Context

当多个数据库操作必须一起成功或失败时，使用事务。下面演示“创建一条留言并读取当前事务内可见的公开留言数”，只操作上面的演示表；计数仅用于展示事务读取，不应作为高并发计数器方案。

func CreateAndCount(ctx context.Context, nickname, content string) (int, error) {
var total int
err := g.DB().Transaction(ctx, func(ctx context.Context, tx gdb.TX) error {
_, err := tx.Model("demo_messages").Data(g.Map{
"nickname": nickname,
"content":  content,
"status":   1,
}).Insert()
if err != nil {
return err
}
total, err = tx.Model("demo_messages").
Where("status", 1).WhereNull("deleted_at").Count()
return err
})
if err != nil {
return 0, err
}
return total, nil
}

该片段还需导入 github.com/gogf/gf/v2/database/gdb。事务闭包返回 nil 时提交，返回错误时回滚；示例显式使用 tx，让事务边界更容易看清。事务文档。

开发时要特别注意：

请求的 ctx 应沿控制器、业务层、DAO 继续传递，不要随手替换成 context.Background()。
事务内遇到错误需要返回；只打印日志再返回 nil，可能导致本应回滚的操作提交。
不在事务里长时间请求外部 HTTP 服务，避免连接和锁一直被占用。
数据库提交与 Redis 操作不属于同一个本地事务，不能假设会一起回滚。
独立后台任务需要自己的生命周期与超时，不能永久依附已结束的请求 Context。

8、错误处理与日志

业务失败与系统失败应区分处理。比如“回复目标不存在”可以返回明确提示；数据库连接串、SQL 和调用栈则留在服务端，不能直接返回给访客。

gerror.Wrap 可以在保留错误链的同时补充操作语境，适合定位“哪一步失败”。不要每一层都重复打印同一个错误，最终处理边界统一记录通常更清晰。错误处理文档。

func CountPublicMessages(ctx context.Context) (int, error) {
total, err := g.DB().Model("demo_messages").Ctx(ctx).
Where("status", 1).WhereNull("deleted_at").Count()
if err != nil {
return 0, gerror.Wrap(err, "查询公开留言总数失败")
}
return total, nil
}

日志建议记录请求标识、操作名、耗时和必要的业务 ID，方便把一次请求串起来。密码、Token、完整请求头和访客的私密信息不作为默认日志内容。

使用 g.Log() 时可通过 logger 配置业务日志的路径、级别和轮转。HTTP Server、ORM 等组件有各自的日志配置，修改 logger 并不意味着所有组件都会采用同样设置。日志组件、日志配置。

9、结合留言和评论场景的设计思路

以下是接口设计建议，与具体框架无关。使用 GoFrame 时，可以把这些规则放在业务层和中间件中。

9.1 分页与楼中楼

留言板使用普通分页即可，例如每页 30 条。文章评论则拆成两个查询入口：

根评论列表：每页最多 30 条，每个根评论先带 3 条回复预览。
某楼层的回复列表：用户点击“查看更多”后，再按游标取下一批。

不要先查所有评论，再在 Go 内存里截取第一页；也不要针对每条根评论单独执行一次回复查询。对于 30 个根评论，可以使用批量查询或窗口函数限制每个根评论的预览数量，避免 N+1 和无限展开。

回复要验证目标仍然存在、属于同一篇文章，并由服务端确定根评论 ID。文章关联标识使用稳定的文章 Key，不把完整域名作为唯一标识，后续换域名时更容易保留讨论记录。

9.2 创建限流

对于公开留言，可以先采用“同一 IP，10 秒内最多创建一次”。多进程部署时应在 Redis 中执行原子操作，例如 SET key value NX EX 10；不要用“先 GET、再 SET”模拟互斥。

限流 Key 是否跨评论、留言共享，需要在产品规则中明确。代理后的真实 IP 只能从可信代理链获取，不能直接相信任意客户端提交的 X-Forwarded-For。IP 限流也不能代替登录权限、内容长度限制和必要的内容审核。

9.3 查询缓存与创建后的可见性

可以从短时间缓存公开列表开始，例如缓存第一页 30 秒。缓存 Key 至少包含文章标识、页码、每页数量和排序规则，不缓存访客邮箱等非公开信息。

创建成功后的流程可以设计为：

数据库提交成功
  → 失效相关列表缓存，或递增文章/留言板的缓存版本
  → 返回已创建的数据
  → 前端立即显示自己的新内容
  → 再刷新列表进行校准

缓存失效必须在数据库提交成功后进行。若先删缓存、再提交，其他请求可能在这段时间读到旧数据库内容，并把旧结果重新写入缓存。即使提交后删除，仍需考虑已经在途的旧查询，因此并发较高时可结合版本号、短 TTL 和前端临时合并策略处理。

单机内存缓存可以作为轻量优化，但多个服务实例不会天然共享。限流和缓存需要跨实例一致时，应明确采用共享存储，并定义 Redis 暂不可用时是降级、拒绝，还是受控直查数据库。

10、开发时容易踩的坑

现象	优先检查
修改接口后路由没出现	API 元数据、控制器生成结果、路由组 `Bind` 是否完整
接口前缀重复	组路径和 `g.Meta path` 是否各写了一次 `/api`
参数校验没按预期执行	是否使用规范路由、`v` 标签是否正确、必填规则和默认值是否冲突
找不到数据库驱动	对应 contrib 驱动是否安装并在启动路径导入
生成的字段与数据库不同	是否更新了表结构并重新执行 DAO 生成
事务没有回滚	闭包是否吞掉错误、操作是否真的使用了事务对象
列表空时返回 `null`	切片是否初始化为空切片，接口契约是否约定为数组
查不到某行却没有报错	不要一律按 `sql.ErrNoRows` 判断；检查所用查询方法及返回对象是否为空
更新“成功”但数据没变	查询条件、更新字段和受影响行数是否符合预期
修改日志配置没生效	修改的是业务 logger，还是 Server / ORM 各自的日志配置
生成后手写代码丢失	是否修改了标明由工具维护的文件
新留言刚发表却看不到	缓存失效时机、在途旧查询与前端列表合并是否正确

当前这篇先覆盖常见的 HTTP 与数据库开发过程。后续可以继续补充登录鉴权、文件上传、定时任务、自动化测试，以及更完整的业务项目示例。

个人网站总结

2026-10-07T18:19:03.000Z

1、基本信息

主域名： daixiaokang.com
www 入口： www.daixiaokang.com（部署时统一跳转至主域名）

2、技术栈

博客框架：Hexo 6.3.0
主题：Butterfly 4.3.1
源码仓库：Github
托管与部署：本网站采用多线部署，包括Vercel + Netlify + Cloudflare + Railway + Fleek + Render + Zeabur + Github Pages 等
评论系统：Twikoo系统 + Vercel部署 + MongoDB提供存储服务
CDN：七牛云
SEO优化：谷歌 + 必应 + 百度
音乐平台：hexo-tag-aplayer + MetingJS
开发语言：HTML5 + CSS3 + JavaScript + Pug + YML等
版权声明：详见CC BY-NC-SA 4.0
文章摘要生成：Post-Abstract-AI

3、网站记录

大学的时候就想搭一个自己的网站，但是迫于自己技术栈的限制没有成功。那个时候主要学习的还是linux系统和kali渗透，接触后端语言是从大二开始，那个时候Golang还没有现在这么火，于是就自学了Go和Java。但是看到学前端的同学可以制作这么炫酷的网页真的非常羡慕。于是在工作的第一年抽出时间搭了自己的网站。使用hexo的原因是因为框架偏前端，易上手。刚开始的时候也尝试过搭建一个可管理的网站，搜了很多模板。但是前端的效果都没有达到自己的预期。虽然现在网站使用的技术个人感觉比较简单，但是效果还是可以接受的。在这里非常感谢网站开源的作者Fomalhuat，借用他的开源版本搭建了自己的网站。

Markdown语法与外挂标签写法汇总

2026-10-07T16:00:00.000Z

1.Markdown语法自带格式

参考：Markdown语法图文全面详解(10分钟学会)

注意：此页面偶尔会存在CSS冲突问题!

1.1 代码块

\```shell
# VSCode终端
hexo clean; hexo s
hexo clean; hexo g; hexo d
git add .; git commit -m "npm publish"; npm version patch;
git push

# Cmder终端
hexo clean && hexo s
hexo clean && hexo g && hexo d
git add . && git commit -m "npm publish" && npm version patch
git push
\```

# VSCode终端
hexo clean; hexo s
hexo clean; hexo g; hexo d
git add .; git commit -m "npm publish"; npm version patch;
git push

# Cmder终端
hexo clean && hexo s
hexo clean && hexo g && hexo d
git add . && git commit -m "npm publish" && npm version patch
git push

1.2 多级标题

# H1
## H2
### H3
#### H4
##### H5
###### H6

见本文章标题!

1.3 文字样式

<u>下划线演示u>

文字**加粗**演示

文字*斜体*演示

文本`高亮`演示

文本~~删除~~线演示

<font size = 5>5号字font>
<font face="黑体">黑体font>
<font color=blue>蓝色font>

<table><tr><td bgcolor=MistyRose>这里的背景色是：MistyRosen，此处输入任意想输入的内容td>tr>table>

下划线演示

文字加粗演示

文字斜体演示

文本高亮演示

文本删除线演示

5号字
黑体
蓝色

这里的背景色是：MistyRosen，此处输入任意想输入的内容

上述要点可参考:【Markdown语法】字体颜色大小及文字底色设置

1.4 引用

>  Java
> 二级引用演示
> MySQL
> >外键
> >
> >事务
> >
> >**行级锁**(引用内部一样可以用格式)
>
> ....

Java
二级引用演示
MySQL
外键
事务
行级锁(引用内部一样可以用格式)
…

1.5 分割线

1
2

---
***

1.6 列表(*,+,-跟空格都可以)

1.6.1 无序列表

* Java
* Python
* ...

+ Java
+ Python
+ ...

- Java
- Python
- ...

Java
Python
…

Java
Python
…

Java
Python
…

1.6.2 有序列表

# 注意后面有空格
1.
2.
3.
4.

1.7 图片

# 本地图片
<img src="/assets/home/optimized/pc_23-cover.webp" alt="示例图片" style="zoom:50%;" />
# 本站静态图片
![背景示例](/assets/home/optimized/pc_22-cover.webp)

本地图片:

本站静态图片:

1.8 表格

| 项目标号 | 资金     | 备注 |
| -------- | -------- | ---- |
| 1        | 100，000 | 无   |
| 2        | 200，000 | 无   |
| 3        | 300,600  | 重要 |

项目标号	资金	备注
1	100，000	无
2	200，000	无
3	300,600	重要

1.9 公式

1
2
3

$$
\Gamma(z)=\int_0^\infty t^{z-1}e^{-t}dt.
$$

$$
\Gamma(z)=\int_0^\infty t^{z-1}e^{-t}dt.
$$

2.Butterfly外挂标签

这部分参考安知鱼:基于Butterfly的外挂标签引入

2.1 行内文本样式 text

{% u 文本内容 %}
{% emp 文本内容 %}
{% wavy 文本内容 %}
{% del 文本内容 %}
{% kbd 文本内容 %}
{% psw 文本内容 %}

1. 带 {% u 下划线 %} 的文本
2. 带 {% emp 着重号 %} 的文本
3. 带 {% wavy 波浪线 %} 的文本
4. 带 {% del 删除线 %} 的文本
5. 键盘样式的文本 {% kbd command %} + {% kbd D %}
6. 密码样式的文本：{% psw 这里没有验证码 %}

带下划线的文本
带着重号的文本
带波浪线的文本
带 ~~删除线~~ 的文本
键盘样式的文本 command + D
密码样式的文本：这里没有验证码

2.2 行内文本 span

1	{% span 样式参数(参数以空格划分), 文本内容 %}

字体: logo, code
颜色: red,yellow,green,cyan,blue,gray
大小: small, h4, h3, h2, h1, large, huge, ultra
对齐方向: left, center, right

- 彩色文字
在一段话中方便插入各种颜色的标签，包括：{% span red, 红色 %}、{% span yellow, 黄色 %}、{% span green, 绿色 %}、{% span cyan, 青色 %}、{% span blue, 蓝色 %}、{% span gray, 灰色 %}。
- 超大号文字
文档「开始」页面中的标题部分就是超大号文字。
{% span center logo large, Volantis %}
{% span center small, A Wonderful Theme for Hexo %}

彩色文字
在一段话中方便插入各种颜色的标签，包括：红色、黄色、绿色、青色、蓝色、灰色。
超大号文字
文档「开始」页面中的标题部分就是超大号文字。
Volantis
A Wonderful Theme for Hexo

2.3 段落文本 p

1	{% p 样式参数(参数以空格划分), 文本内容 %}

字体: logo, code
颜色: red,yellow,green,cyan,blue,gray
大小: small, h4, h3, h2, h1, large, huge, ultra
对齐方向: left, center, right

- 彩色文字
在一段话中方便插入各种颜色的标签，包括：{% p red, 红色 %}、{% p yellow, 黄色 %}、{% p green, 绿色 %}、{% p cyan, 青色 %}、{% p blue, 蓝色 %}、{% p gray, 灰色 %}。
- 超大号文字
文档「开始」页面中的标题部分就是超大号文字。
{% p center logo large, Volantis %}
{% p center small, A Wonderful Theme for Hexo %}

彩色文字
在一段话中方便插入各种颜色的标签，包括：
红色
、
黄色
、
绿色
、
青色
、
蓝色
、
灰色
。
超大号文字
文档「开始」页面中的标题部分就是超大号文字。

Volantis

A Wonderful Theme for Hexo

2.4 引用note

note:
  # Note tag style values:
  #  - simple    bs-callout old alert style. Default.
  #  - modern    bs-callout new (v2-v3) alert style.
  #  - flat      flat callout style with background, like on Mozilla or StackOverflow.
  #  - disabled  disable all CSS styles import of note tag.
  style: simple
  icons: false
  border_radius: 3
  # Offset lighter of background in % for modern and flat styles (modern: -12 | 12; flat: -18 | 6).
  # Offset also applied to label tag variables. This option can work with disabled note tag.
  light_bg_offset: 0

# 自带icon
{% note [class] [no-icon] [style] %}
Any content (support inline tags too.io).
{% endnote %}
# 外部icon
{% note [color] [icon] [style] %}
Any content (support inline tags too.io).
{% endnote %}

1.自带icon

参数	用法
class	【可选】标识，不同的标识有不同的配色（ default / primary / success / info / warning / danger ）
no-icon	【可选】不显示 icon
style	【可选】可以覆盖配置中的 style （simple/modern/flat/disabled）

2.外部icon

参数	用法
class	【可选】标识，不同的标识有不同的配色（ default / blue / pink / red / purple / orange / green ）
no-icon	【可选】可配置自定义 icon (只支持 fontawesome 图标, 也可以配置 no-icon )
style	【可选】可以覆盖配置中的 style （simple/modern/flat/disabled）

1.自带icon