Aemeath

从 smart-doc 到自定义 API 管理

Tue, 03 Nov 2026 00:00:00 GMT

背景#

项目用 smart-doc 生成 API 文档，但 smart-doc 默认输出的是静态 HTML 或 Markdown，没法直接集成到后台管理系统里。Knife4j / Swagger UI 需要运行时暴露接口，生产环境不想带那一套。

所以思路是：smart-doc 只负责生成 OpenAPI 规范，我们自己写一个解析器把规范转成自定义的数据结构，存到业务数据库，前端按需展示。

生成 OpenAPI 规范#

Maven 插件配置#

1
<build>
2
  <plugins>
3
    <plugin>
4
      <groupId>org.springframework.boot</groupId>
5
      <artifactId>spring-boot-maven-plugin</artifactId>
6
    </plugin>
7
    <plugin>
8
      <groupId>com.ly.smart-doc</groupId>
9
      <artifactId>smart-doc-maven-plugin</artifactId>
10
      <version>3.1.2</version>
11
      <configuration>
12
        <configFile>./src/main/resources/smart-doc.json</configFile>
13
        <projectName>${project.description}</projectName>
14
      </configuration>
15
      <executions>
16
        <execution>
17
          <phase>compile</phase>
18
          <goals>
19
            <goal>openapi</goal>
20
          </goals>
21
        </execution>
22
      </executions>
23
    </plugin>
24
  </plugins>
25
</build>

展开收起

smart-doc.json 放到模块的 resources 目录下：

1
{
2
  "outPath": "src/main/resources/static/doc",
3
  "projectName": "SmartDoc Demo",
4
  "allInOne": true,
5
  "serverUrl": "http://localhost:8080",
6
  "packageFilters": "com.zmr.train.controller",
7
  "sourceCodePaths": [
8
    {
9
      "path": "src/main/java",
10
      "desc": "Main Source"
11
    }
12
  ],
13
  "customResponseFields": [
14
    {
15
      "name": "params",
16
      "ignore": true
17
    }
18
  ]
19
}

展开收起

泛型返回值要求#

smart-doc 要正确解析泛型，返回值类必须写清楚泛型参数：

1
@Data
2
@EqualsAndHashCode(callSuper = false)
3
@Accessors(chain = true)
4
public class ApiResult<T> {
5
    /** 状态码 */
6
    private int code;
7
    /** 提示消息 */
8
    private String msg;
9
    /** 数据内容 */
10
    private T data;
11

12
    public static <T> ApiResult<T> success(T data) {
13
        return new ApiResult<>(200, "操作成功", data);
14
    }
15
    public static <T> ApiResult<T> error(String msg) {
16
        return new ApiResult<>(500, msg, null);
17
    }
18
}
19

20
@Data
21
@EqualsAndHashCode(callSuper = false)
22
@Accessors(chain = true)
23
public class PageDTO<T> {
24
    /** 总记录数 */
25
    private long total;
26
    /** 列表数据 */
27
    private List<T> rows;
28
    private int code;
29
    private String msg;
30
}

展开收起

Controller 返回值这样写 smart-doc 才能正确识别泛型：

1
// 普通响应
2
@GetMapping("/stats/total")
3
public ApiResult<StatsTotalVO> statsTotal(@RequestParam Long courseId) { ... }
4

5
// 分页响应
6
@PostMapping("/stats/student")
7
public ApiResult<PageDTO<StudentStatsVO>> statsStudent(@RequestBody Query query) { ... }

生成的 OpenAPI 规范#

用 openapi goal 在 IDEA 右侧直接执行，生成的 OpenAPI 3.1.0 大致如下（截取一条接口）：

1
{
2
  "openapi": "3.1.0",
3
  "info": {
4
    "title": "出海项目course模块",
5
    "version": "v1.0.0"
6
  },
7
  "paths": {
8
    "/courseInfo/api/stats/total": {
9
      "get": {
10
        "summary": "statsTotal",
11
        "parameters": [
12
          { "name": "courseId", "in": "query", "schema": { "type": "integer" } }
13
        ],
14
        "responses": {
15
          "200": {
16
            "content": {
17
              "*/*": {
18
                "schema": { "$ref": "#/components/schemas/d6ecb03fb627b0072e25b42bc00bfbce" }
19
              }
20
            }
21
          }
22
        }
23
      }
24
    }
25
  },
26
  "components": {
27
    "schemas": {
28
      "d6ecb03fb627b0072e25b42bc00bfbce": {
29
        "type": "object",
30
        "properties": {
31
          "code": { "type": "integer", "description": "状态码", "example": 200 },
32
          "msg": { "type": "string", "description": "提示消息", "example": "操作成功" },
33
          "data": { "$ref": "#/components/schemas/1c2473eb77b19e52e32977bcbc686c6c" }
34
        }
35
      }
36
    }
37
  }
38
}

展开收起

每个字段的描述（description）来自 Java 代码里的注释，mock 值来自 @mock 注解。数据结构通过 $ref 互相引用。

解析 OpenAPI 规范#

依赖#

Terminal window

1
implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
2
implementation 'org.springframework.boot:spring-boot-starter-web'
3
implementation 'io.swagger.parser.v3:swagger-parser:2.1.20'
4
implementation 'com.alibaba.fastjson2:fastjson2:2.0.61'
5
compileOnly 'org.projectlombok:lombok'
6
runtimeOnly 'com.h2database:h2'
7
annotationProcessor 'org.projectlombok:lombok'

核心依赖就一个：swagger-parser。它能把 OpenAPI JSON 解析成 Java 的 OpenAPI 对象模型，剩下的就是遍历和转换。

实体设计#

1
@Setter
2
@Getter
3
@Entity
4
public class DocApi {
5
    @Id
6
    @GeneratedValue(strategy = GenerationType.IDENTITY)
7
    private Integer id;
8

9
    /** 接口名称 */
10
    private String name;
11
    /** 接口地址 */
12
    private String url;
13
    /** 调用方式 (GET/POST等) */
14
    private String method;
15
    /** 认证方式 */
16
    private String authMethod;
17

18
    /** 请求参数 (Query String) */
19
    @JdbcTypeCode(SqlTypes.JSON)
20
    private List<Map<String, Object>> requestParams;
21

22
    /** Body 参数 (JSON 请求体) */
23
    @JdbcTypeCode(SqlTypes.JSON)
24
    private List<Map<String, Object>> bodyParams;
25

26
    /** 响应参数 */
27
    @JdbcTypeCode(SqlTypes.JSON)
28
    private List<Map<String, Object>> respParams;
29
}

展开收起

用 JPA 的 JSON 列类型（需要数据库支持，如 PostgreSQL 的 jsonb），参数结构用 List<Map> 存，灵活不用建额外关联表。

解析核心代码#

1
public void upload(MultipartFile file) throws IOException {
2
    String content = StreamUtils.copyToString(
3
        file.getInputStream(), StandardCharsets.UTF_8);
4

5
    // 1. 解析 OpenAPI 内容
6
    SwaggerParseResult result = new OpenAPIV3Parser()
7
        .readContents(content, null, null);
8
    OpenAPI openAPI = result.getOpenAPI();
9
    Map<String, Schema> allSchemas = openAPI.getComponents().getSchemas();
10

11
    List<DocApi> apiList = new ArrayList<>();
12

13
    // 2. 遍历 Paths，每个接口转成一个 DocApi
14
    openAPI.getPaths().forEach((url, pathItem) -> {
15
        pathItem.readOperationsMap().forEach((method, operation) -> {
16
            DocApi doc = new DocApi();
17
            doc.setName(operation.getSummary());
18
            doc.setUrl(url);
19
            doc.setMethod(method.name());
20

21
            // 2a. 解析 Query 参数
22
            doc.setRequestParams(parseParameters(operation.getParameters()));
23

24
            // 2b. 解析 Body 参数
25
            doc.setBodyParams(parseBodyParams(
26
                operation.getRequestBody(), allSchemas));
27

28
            // 2c. 解析响应参数（递归展开）
29
            doc.setRespParams(parseResponseParams(
30
                operation.getResponses(), allSchemas));
31

32
            apiList.add(doc);
33
        });
34
    });
35

36
    if (!apiList.isEmpty()) {
37
        docApiDao.saveAll(apiList);
38
    }
39
}
40

41
/** 解析 Query 参数 */
42
private List<Map<String, Object>> parseParameters(
43
        List<Parameter> parameters) {
44
    if (parameters == null) return Collections.emptyList();
45
    List<Map<String, Object>> result = new ArrayList<>();
46
    for (Parameter p : parameters) {
47
        Map<String, Object> map = new HashMap<>();
48
        map.put("fieldName", p.getDescription());
49
        map.put("fieldCode", p.getName());
50
        map.put("fieldType", resolveType(p.getSchema()));
51
        result.add(map);
52
    }
53
    return result;
54
}
55

56
/** 解析 Body 参数（处理 $ref 引用） */
57
private List<Map<String, Object>> parseBodyParams(
58
        RequestBody requestBody, Map<String, Schema> allSchemas) {
59
    if (requestBody == null || requestBody.getContent() == null)
60
        return Collections.emptyList();
61

62
    MediaType mt = requestBody.getContent().get("application/json");
63
    if (mt == null || mt.getSchema() == null)
64
        return Collections.emptyList();
65

66
    Schema<?> schema = resolveRef(mt.getSchema(), allSchemas);
67
    if (schema == null || schema.getProperties() == null)
68
        return Collections.emptyList();
69

70
    List<Map<String, Object>> result = new ArrayList<>();
71
    schema.getProperties().forEach((name, fieldSchema) -> {
72
        result.add(extractFieldInfo(name, fieldSchema, null));
73
    });
74
    return result;
75
}
76

77
/** 解析响应参数（递归展开嵌套结构） */
78
private List<Map<String, Object>> parseResponseParams(
79
        ApiResponses responses, Map<String, Schema> allSchemas) {
80
    if (responses == null) return Collections.emptyList();
81

82
    ApiResponse resp = responses.get("200");
83
    if (resp == null || resp.getContent() == null)
84
        return Collections.emptyList();
85

86
    MediaType mt = resp.getContent().get("application/json");
87
    if (mt == null) mt = resp.getContent().get("*/*");
88
    if (mt == null || mt.getSchema() == null)
89
        return Collections.emptyList();
90

91
    List<Map<String, Object>> result = new ArrayList<>();
92
    parseSchemaRecursive(mt.getSchema(), allSchemas, result, "");
93
    return result;
94
}
95

96
/**
97
 * 递归解析 Schema，展平为带路径前缀的字段列表
98
 * 如：data.teachers, data.countryStats[].countryName
99
 */
100
private void parseSchemaRecursive(Schema<?> schema,
101
        Map<String, Schema> allSchemas,
102
        List<Map<String, Object>> result, String parentName) {
103
    if (schema == null) return;
104

105
    schema = resolveRef(schema, allSchemas);
106
    if (schema == null || schema.getProperties() == null) return;
107

108
    for (Map.Entry<String, Schema> entry :
109
            schema.getProperties().entrySet()) {
110
        String fieldCode = entry.getKey();
111
        Schema<?> fieldSchema = entry.getValue();
112
        Schema<?> resolved = resolveRef(fieldSchema, allSchemas);
113

114
        String fullName = parentName.isEmpty()
115
            ? fieldCode : parentName + "." + fieldCode;
116

117
        Map<String, Object> fieldInfo = new HashMap<>();
118
        fieldInfo.put("fieldCode", fullName);
119
        fieldInfo.put("fieldName", fieldSchema.getDescription() != null
120
            ? fieldSchema.getDescription()
121
            : (resolved != null ? resolved.getDescription() : ""));
122
        fieldInfo.put("fieldType", resolved != null
123
            ? resolved.getType() : fieldSchema.getType());
124
        result.add(fieldInfo);
125

126
        // 对象类型 -> 递归
127
        if (resolved != null && "object".equals(resolved.getType())) {
128
            parseSchemaRecursive(resolved, allSchemas, result, fullName);
129
        }
130
        // 数组类型 -> 递归 items
131
        else if (fieldSchema instanceof ArraySchema) {
132
            Schema<?> itemsSchema =
133
                ((ArraySchema) fieldSchema).getItems();
134
            // items 可能是 $ref，需要先解引用
135
            itemsSchema = resolveRef(itemsSchema, allSchemas);
136
            parseSchemaRecursive(
137
                itemsSchema, allSchemas, result, fullName + "[]");
138
        }
139
    }
140
}
141

142
// ---- 工具方法 ----
143

144
/** 获取字段类型，兼容 OpenAPI 3.1 的 types 数组 */
145
private String resolveType(Schema<?> schema) {
146
    if (schema == null) return "object";
147
    if (schema.getType() != null) return schema.getType();
148
    if (schema.getTypes() != null && !schema.getTypes().isEmpty())
149
        return schema.getTypes().iterator().next();
150
    return "object";
151
}
152

153
/** 解 $ref 引用，返回真实 Schema */
154
private Schema<?> resolveRef(Schema<?> schema,
155
        Map<String, Schema> allSchemas) {
156
    if (schema == null) return null;
157
    if (schema.get$ref() != null) {
158
        String refName = schema.get$ref()
159
            .replace("#/components/schemas/", "");
160
        return allSchemas.get(refName);
161
    }
162
    return schema;
163
}
164

165
/** 提取字段基本信息 */
166
private Map<String, Object> extractFieldInfo(
167
        String name, Schema<?> schema, String desc) {
168
    Map<String, Object> map = new HashMap<>();
169
    map.put("fieldName", name);
170
    map.put("description", desc != null ? desc : "");
171
    map.put("fieldType", resolveType(schema));
172
    return map;
173
}

展开收起

几个关键点：

$ref 引用解析：OpenAPI 规范大量使用 $ref 指向 components/schemas，必须用 resolveRef() 把所有引用解掉才能拿到具体字段
OpenAPI 3.1 兼容：3.1 版本 type 字段改成了 types 数组，resolveType() 做了兼容处理
数组 items 解引用：ArraySchema 的 items 也可能是个 $ref，需要先解引用再递归
字段路径前缀：用 data.teachers、data.countryStats[].countryName 这种路径字符串表示字段的层级关系，前端展示时容易解析

总结#

这套方案的优点是：

生成与解析分离：smart-doc 只管生成，不侵入运行时
数据结构自主可控：存到自己的业务表里，想怎么展示、搜索、关联都方便
增量更新：重新生成 OpenAPI JSON 上传即可，不需要重启服务

后续可以考虑的方向：

接口版本对比（Diff）：两个版本的 OpenAPI JSON diff，标记新增/废弃/变更的接口
自动化 CI 集成：Maven 编译阶段自动生成，上传到管理平台
接口 Mock 数据生成：基于 OpenAPI schema 的 example 自动生成 Mock 接口

Spring Validation 参数校验

Tue, 03 Nov 2026 00:00:00 GMT

参数校验这件事，麻烦的从来不是写 @NotNull，而是分组、嵌套和错误信息怎么统一。

两个注解别混用#

@Valid 是 JSR-303 标准注解，标在方法参数、字段上，触发级联校验。
@Validated 是 Spring 的，多了 groups 属性，能标在类上做方法级校验。

想让分组生效，就得用 @Validated；只校验一个 DTO，@Valid 就够。

1
@RestController
2
@Validated
3
public class UserController {
4

5
    @PostMapping("/users")
6
    public User create(@Valid @RequestBody UserForm form) { ... }
7

8
    @PostMapping("/users/batch")
9
    public void batch(@Validated(Batch.class) @RequestBody List<UserForm> forms) { ... }
10
}

分组#

新增和修改的校验规则通常不一样：新增时 id 必须为空，修改时必须不为空。

1
public interface Create {}
2
public interface Update {}
3

4
public class UserForm {
5
    @Null(groups = Create.class, message = "新增不能带 id")
6
    @NotNull(groups = Update.class, message = "修改必须带 id")
7
    private Long id;
8

9
    @NotBlank(groups = {Create.class, Update.class})
10
    private String name;
11
}

不写 groups 的约束属于 Default 组；一旦指定了分组，Default 就不会被触发，这点最容易踩。

嵌套对象#

集合和嵌套对象不会自动校验，必须在字段上加 @Valid：

1
public class OrderForm {
2
    @Valid
3
    @NotEmpty
4
    private List<ItemForm> items;
5

6
    @Valid
7
    @NotNull
8
    private AddressForm address;
9
}

少一个 @Valid，里面写再多约束都不生效。

自定义注解#

1
@Target({ElementType.FIELD})
2
@Retention(RetentionPolicy.RUNTIME)
3
@Constraint(validatedBy = PhoneValidator.class)
4
public @interface Phone {
5
    String message() default "手机号格式不对";
6
    Class<?>[] groups() default {};
7
    Class<? extends Payload>[] payload() default {};
8
}
9

10
public class PhoneValidator implements ConstraintValidator<Phone, String> {
11
    private static final Pattern P = Pattern.compile("^1[3-9]\\d{9}$");
12
    @Override
13
    public boolean isValid(String value, ConstraintValidatorContext ctx) {
14
        return value == null || P.matcher(value).matches();
15
    }
16
}

展开收起

注意 isValid 里对 null 要放行，空值交给 @NotNull 管，否则两个注解的语义会打架。

统一错误返回#

1
@RestControllerAdvice
2
public class ValidationHandler {
3
    @ExceptionHandler(MethodArgumentNotValidException.class)
4
    public ResponseEntity<Map<String, String>> handle(MethodArgumentNotValidException e) {
5
        Map<String, String> errors = e.getBindingResult().getFieldErrors().stream()
6
            .collect(Collectors.toMap(FieldError::getField,
7
                f -> Objects.requireNonNullElse(f.getDefaultMessage(), "参数不合法"),
8
                (a, b) -> a));
9
        return ResponseEntity.badRequest().body(errors);
10
    }
11
}

方法参数校验失败抛的是 ConstraintViolationException，不是上面这个，两个都要接。

坑#

@Validated 标在类上才会让方法参数上的约束生效，标在方法上没用。
校验发生在参数绑定之后，所以 JSON 结构错了会先抛反序列化异常，压根到不了校验。
分组校验下 @Valid 不带 groups，级联进去的还是 Default 组。

为什么我最终把绿联 NAS 重装成了 Debian 13

Mon, 27 Jul 2026 00:00:00 GMT

绿联原系统不是不能用。

如果只是当一台成品 NAS，它其实挺省心：应用商店、相册、远程访问、存储管理，能点的地方都给你做好了。对很多人来说，这就是 NAS 应该有的样子。

但我越用越别扭。

我真正想要的不是一个包装好的 NAS 面板，而是一台普通 Linux 服务器。Docker 想怎么跑就怎么跑，日志写到哪里能说清楚，机械盘为什么被唤醒能查出来，出了问题也能按 Debian 的资料去排。

所以最后我把这台绿联 NAS 重装成了 Debian 13。

安装本身并不复杂。麻烦的是后面这一串东西：旧数据盘不是普通 ext4，绿联的 ext4 带了 Debian 不认识的特性位；Docker 数据目录要重新规划；普通用户权限不能乱给；机械盘也不是格式化完就会自动休眠。

这篇记录的是这次迁移真正踩到的地方。

为什么要重装#

我不是因为原系统坏了才重装的。它没有突然崩，也没有出现一个必须立刻逃离的故障。

真正让我下决心的，是长期使用里的几个小问题。

更新节奏跟着厂商走#

成品 NAS 系统的稳定性不错，但内核、Docker、命令行工具和系统组件都跟着厂商更新。

如果只是共享文件，这不算大事。可我的 NAS 上会跑不少 Docker 服务，遇到问题时，我更希望底层是一套标准 Debian。至少路径、日志、服务管理、包管理都能按常规 Linux 的方式查。

后台组件太多#

原系统自带相册、媒体、索引、搜索、云服务、通知和设备管理。

这些东西不是没用，只是我已经有自己的相册、媒体服务、网盘和监控。原系统里很多功能对我来说就成了重复建设。

更烦的是后台扫描和索引。它不一定占很多 CPU，但它可能访问机械盘。机械盘一被访问，就很难安静下来。

我想知道硬盘到底在干什么#

我关心的不是界面上有没有显示“休眠”，而是更具体的事：

盘片现在是不是真的停了；
是哪个进程碰了磁盘；
一天里被唤醒了几次；
数据库、日志、缓存是不是都在 SSD；
SMART 检查会不会把休眠盘叫醒。

这些在 Debian 里都能查。hdparm、smartctl、iotop、fuser、journalctl，工具都在那里。

我最后想要的结构也很简单：

1
系统和高频服务跑在 SSD
2
Docker、数据库、日志和缓存写到 SSD
3
机械盘只放媒体和冷数据
4
需要时唤醒，空闲后休眠
5
每一次唤醒都能查到记录

覆盖系统盘前，先备份#

这台机器原本有一块系统 SSD。原系统、恢复分区、厂商数据都在上面。

我想过几种方案：再加一块 SSD 装 Debian，用 U 盘跑系统，或者直接覆盖原系统盘。最后还是选了最直接的方式：备份后覆盖系统 SSD。

原因也不复杂。系统 SSD 本来就是用来装系统的，Debian 占用不大，我也不想为了保留原系统再长期占一块盘。

但覆盖之前一定要留退路。

成品 NAS 的系统盘通常不只是一个根分区。它可能还有 EFI、恢复分区、工厂数据、隐藏配置和引导信息。只复制几个分区不放心，所以我直接做整盘镜像。

先确认系统盘：

Terminal window

1
lsblk -o NAME,SIZE,MODEL,SERIAL,FSTYPE,MOUNTPOINTS

假设系统盘是 /dev/nvmeXn1，备份盘挂载在 /mnt/backup：

Terminal window

1
sudo dd if=/dev/nvmeXn1 bs=64M status=progress | \
2
  gzip -1 -c > /mnt/backup/ugreen-system-disk.img.gz
3
sync

再保存校验值：

Terminal window

1
sha256sum /mnt/backup/ugreen-system-disk.img.gz \
2
  > /mnt/backup/ugreen-system-disk.img.gz.sha256
3
sha256sum -c /mnt/backup/ugreen-system-disk.img.gz.sha256

这份镜像不是为了日常用，只是为了以后真的后悔时还有办法回去。

恢复时方向反过来：

Terminal window

1
gzip -dc /mnt/backup/ugreen-system-disk.img.gz | \
2
  sudo dd of=/dev/nvmeXn1 bs=64M status=progress conv=fsync

dd 不会提醒你选错盘。设备名、容量、型号、序列号都要核对清楚。

安装 Debian 时也一样。最稳妥的做法是只保留系统盘；如果不方便拔盘，就在安装器里反复确认目标磁盘，不要把 Debian 装到机械数据盘上。

旧数据盘没有直接挂上#

Debian 装好后，我第一反应是把旧数据盘挂起来。

我原本以为这一步不会太难。底层还是 Linux，文件系统看起来也是 ext4。就算中间套了 RAID 或 LVM，装上工具以后应该也能识别。

实际不是这样。

旧盘大概是这个结构：

1
物理磁盘
2
└── 单盘 mdadm RAID1
3
    └── LVM
4
        └── ext4 文件系统

这个“单盘 RAID1”看着怪，但确实存在。所以不能直接：

Terminal window

1
mount /dev/sdX /mnt/old

要先装工具：

Terminal window

1
sudo apt install -y mdadm lvm2

然后扫描和激活：

Terminal window

1
sudo mdadm --assemble --scan
2
sudo pvscan
3
sudo vgscan
4
sudo vgchange -ay
5
lsblk -f
6
sudo lvs
7
sudo vgs

到这里，mdadm 和 LVM 都能识别，逻辑卷也能看到。

真正卡住的是最后一步：挂载 ext4。

旧 ext4 卡在一个未知特性位上#

继续用 dumpe2fs 看文件系统：

Terminal window

1
sudo dumpe2fs -h /dev/mapper/<旧逻辑卷>

核心报错是：

1
Filesystem has unsupported feature(s)

再看超级块，发现 incompat 标记里有一个 Debian 标准 e2fsprogs 不认识的位：

1
0x20000000

这就不是普通 ext4 损坏，也不是单纯的 mdadm 或 LVM 问题了。

绿联系统在 ext4 上加了额外特性。Debian 工具看到未知的 incompat 位，会拒绝挂载。这个行为其实是对的。它不知道这个位意味着什么，就不应该假装知道，然后继续读写。

这时候最容易想到的办法，是把标记清掉：

Terminal window

1
tune2fs -O ...
2
debugfs -w ...
3
e2fsck -y ...

我没有这么做。

未知标记背后可能不只是一个无意义开关，也可能对应厂商改过的工具链或磁盘结构。强行清掉之后，文件系统也许表面上能挂载，但后续读写反而可能把数据弄坏。

社区恢复工具，以及我为什么没继续#

后来我查到一个社区项目：

1
ugreen-os-ext4-recovery

它不是简单地把标记抹掉，而是用打过补丁的 e2fsprogs 去识别绿联增加的 0x20000000 incompat 位，再尝试恢复或挂载。

这个方向比直接改超级块靠谱。但实际操作起来，至少要做几件事：

编译定制工具；
看懂恢复脚本会改什么；
最好先做整盘镜像；
在副本上验证，不直接动原盘；
接受社区逆向工具可能不完整的风险。

如果盘里是不可替代的数据，我会继续走这条路。

但我的旧盘里主要是可以重新获取的媒体文件。为了这些数据再准备镜像空间、编译工具、验证补丁，投入已经超过了数据本身的价值。

最后只能接受现实：旧结构不恢复了，清空重建。

清掉旧结构，重建标准 ext4#

放弃旧数据后，要把旧盘上的 mdadm、LVM、文件系统签名和分区表都清掉。

操作前再次确认磁盘：

Terminal window

1
lsblk -o NAME,SIZE,MODEL,SERIAL,FSTYPE,MOUNTPOINTS

停止旧阵列和 LVM 后：

Terminal window

1
sudo wipefs -a /dev/sdX
2
sudo mdadm --zero-superblock /dev/sdX

再重新建立 GPT：

Terminal window

1
sudo parted /dev/sdX --script mklabel gpt
2
sudo parted /dev/sdX --script mkpart primary 0% 100%

NVMe 也是同样思路，只是设备名通常类似 /dev/nvmeXn1。

最后每块数据盘都变成：

1
GPT
2
└── 单一 ext4 分区

不再套 mdadm，也不再套 LVM。

对我这种不需要 RAID 的个人 NAS 来说，这样更直观。哪块盘出问题，直接看那块盘；换系统、迁移数据、排查故障，也少一层东西要猜。

机械盘和 SSD 的格式化参数#

机械盘和 SSD 都可以用 ext4，但用途不一样。

机械盘主要放电影、剧集、镜像、备份包这类大文件，我用了：

Terminal window

1
sudo mkfs.ext4 \
2
  -T largefile4 \
3
  -m 0 \
4
  -L data-hdd \
5
  /dev/sdX1

-T largefile4 主要是减少 inode 数量，不会让大文件读写突然变快。如果盘里有大量小文件，就不适合这么格式化。

SSD 用来放 Docker、数据库、应用配置和缓存，文件大小更杂，直接普通 ext4：

Terminal window

1
sudo mkfs.ext4 \
2
  -m 0 \
3
  -L data-ssd \
4
  /dev/nvmeXn1p1

我没有关闭 lazy inode 初始化。

ext4 默认会启用 lazy inode table initialization。格式化会很快完成，但第一次挂载后，内核还会在后台慢慢初始化 inode 表。后面机械盘长时间不休眠，原因之一就是它。

这不是异常写入，也不是硬盘故障。它只是一次性后台任务。

用 UUID 挂载#

不要长期依赖 /dev/sda1、/dev/sdb1。设备名可能因为启动顺序变化而交换。

查看 UUID：

Terminal window

1
lsblk -f
2
sudo blkid

创建挂载点：

Terminal window

1
sudo mkdir -p /mnt/hdd1 /mnt/hdd2 /mnt/ssd

/etc/fstab 示例：

1
UUID=<机械盘1-UUID> /mnt/hdd1 ext4 defaults,noatime,nofail 0 2
2
UUID=<机械盘2-UUID> /mnt/hdd2 ext4 defaults,noatime,nofail 0 2
3
UUID=<SSD-UUID>     /mnt/ssd  ext4 defaults,noatime,nofail 0 2

检查：

Terminal window

1
sudo systemctl daemon-reload
2
sudo mount -a
3
findmnt --verify
4
lsblk -o NAME,SIZE,FSTYPE,LABEL,UUID,MOUNTPOINTS

noatime 可以减少读取文件时的无意义写入。nofail 可以避免某块数据盘异常时让整个系统卡在启动阶段。

不过，如果 Docker 数据放在 SSD 上，还要给 Docker 加挂载依赖。否则 SSD 没挂上时，Docker 可能直接写进系统盘里的 /mnt/ssd 空目录。

SSD 的 TRIM#

Debian 自带 fstrim.timer。我没有在 /etc/fstab 里长期使用在线 discard。

启用：

Terminal window

1
sudo systemctl enable --now fstrim.timer

查看：

Terminal window

1
systemctl status fstrim.timer --no-pager
2
systemctl list-timers fstrim.timer

手动测试：

Terminal window

1
sudo fstrim -v /mnt/ssd

新格式化的空 SSD 第一次执行时，显示接近整盘容量被 trim，是正常现象。

Docker 数据放到 SSD#

Docker 程序本身还是通过 APT 安装在系统盘：

1
/usr/bin/docker
2
/usr/bin/dockerd
3
/etc/docker
4
systemd 服务

真正要搬到 SSD 的，是镜像、容器可写层、containerd 快照、volume、构建缓存和容器日志。

假设 SSD 挂载在 /mnt/ssd：

Terminal window

1
sudo mkdir -p /mnt/ssd/docker/engine
2
sudo mkdir -p /mnt/ssd/docker/containerd

Docker 配置：

Terminal window

1
sudo mkdir -p /etc/docker
2

3
sudo tee /etc/docker/daemon.json >/dev/null <<'EOF'
4
{
5
  "data-root": "/mnt/ssd/docker/engine",
6
  "log-driver": "local",
7
  "log-opts": {
8
    "max-size": "20m",
9
    "max-file": "3"
10
  }
11
}
12
EOF
13

14
python3 -m json.tool /etc/docker/daemon.json

containerd 配置：

Terminal window

1
sudo mkdir -p /etc/containerd
2

3
sudo tee /etc/containerd/config.toml >/dev/null <<'EOF'
4
version = 2
5

6
root = "/mnt/ssd/docker/containerd"
7
state = "/run/containerd"
8
EOF

再加挂载依赖，防止 SSD 没挂上时 Docker 写系统盘：

Terminal window展开收起

1
sudo mkdir -p /etc/systemd/system/docker.service.d
2

3
sudo tee /etc/systemd/system/docker.service.d/storage.conf >/dev/null <<'EOF'
4
[Unit]
5
RequiresMountsFor=/mnt/ssd
6
EOF
7

8
sudo mkdir -p /etc/systemd/system/containerd.service.d
9

10
sudo tee /etc/systemd/system/containerd.service.d/storage.conf >/dev/null <<'EOF'
11
[Unit]
12
RequiresMountsFor=/mnt/ssd
13
EOF
14

15
sudo systemctl daemon-reload

展开收起

安装 Docker 官方版本：

Terminal window展开收起

1
sudo apt update
2
sudo apt install -y ca-certificates curl
3

4
sudo install -m 0755 -d /etc/apt/keyrings
5
sudo curl -fsSL https://download.docker.com/linux/debian/gpg \
6
  -o /etc/apt/keyrings/docker.asc
7
sudo chmod a+r /etc/apt/keyrings/docker.asc
8

9
sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null <<EOF
10
Types: deb
11
URIs: https://download.docker.com/linux/debian
12
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
13
Components: stable
14
Architectures: $(dpkg --print-architecture)
15
Signed-By: /etc/apt/keyrings/docker.asc
16
EOF
17

18
sudo apt update
19
sudo apt install -y \
20
  docker-ce \
21
  docker-ce-cli \
22
  containerd.io \
23
  docker-buildx-plugin \
24
  docker-compose-plugin

展开收起

验证：

Terminal window

1
systemctl is-active docker
2
systemctl is-active containerd
3
sudo docker info --format 'Docker Root Dir: {{.DockerRootDir}}'
4
sudo containerd config dump | grep -E '^(version|root|state)'
5
sudo docker run --rm hello-world

Docker 内部目录不要随便 chown#

为了方便，很容易想直接：

Terminal window

1
sudo chown -R <用户>:<用户> /mnt/ssd/docker

我不建议这么做。

Docker 的 engine 和 containerd 目录里有内部数据、快照和元信息，应该继续由 root 管理。普通用户只需要管理 Compose 文件。

我最后用的是这种结构：

1
/mnt/ssd/docker
2
├── engine          root 管理
3
├── containerd      root 管理
4
└── file            普通用户管理
5
    └── stacks

创建 Compose 目录：

Terminal window

1
sudo mkdir -p /mnt/ssd/docker/file/stacks
2
sudo chown -R <用户>:<用户> /mnt/ssd/docker/file
3
sudo chmod 755 /mnt/ssd/docker

以后 Compose 文件放在 /mnt/ssd/docker/file/stacks，不要进 engine、containerd 里手动改。

机械盘为什么一直不休眠#

硬盘状态可以用：

Terminal window

1
sudo hdparm -C /dev/sdX

active/idle 表示盘片还在转，standby 才是待机。

新格式化后，我发现两块机械盘一整夜都没有休眠，写入计数还在慢慢增加。

查看写入计数：

Terminal window

1
awk '{print $7}' /sys/block/sdX/stat

隔一分钟再看，数字仍然在涨。

继续查：

Terminal window

1
ps -e -o pid,comm,wchan:40 | grep -E 'ext4lazyinit|jbd2/sd'
2
sudo apt install -y psmisc
3
sudo fuser -vm /mnt/hdd1

没有发现 Jellyfin、Docker、数据库这类用户进程，只有内核挂载。

最后确认原因是：

1
ext4lazyinit

也就是 ext4 的延迟 inode 表初始化。

它是新格式化 ext4 后的一次性后台任务，写入速度很低，主要代价只是让硬盘多转几个小时。

这时候不要反复强制休眠：

Terminal window

1
sudo hdparm -y /dev/sdX

后台任务很快又会把盘叫醒，启停次数反而增加。

检查是否结束：

Terminal window

1
ps -C ext4lazyinit -o pid,etime,comm

只有表头、没有进程，就说明初始化已经完成。

设置机械盘自动休眠#

确认没有持续写入后，我设置空闲 30 分钟休眠：

Terminal window

1
sudo hdparm -S 241 /dev/sdX

241 表示 30 分钟。

半小时后查看：

Terminal window

1
sudo hdparm -C /dev/sdX

如果显示：

1
standby

就说明成功了。

hdparm -S 重启后可能丢失，所以可以做成 systemd 服务。长期使用最好写 /dev/disk/by-id/，不要依赖 /dev/sda。

Terminal window展开收起

1
sudo tee /etc/systemd/system/hdd-spindown.service >/dev/null <<'EOF'
2
[Unit]
3
Description=Set HDD spindown timeout
4
After=local-fs.target
5

6
[Service]
7
Type=oneshot
8
ExecStart=/usr/sbin/hdparm -S 241 /dev/disk/by-id/<机械盘1>
9
ExecStart=/usr/sbin/hdparm -S 241 /dev/disk/by-id/<机械盘2>
10
RemainAfterExit=yes
11

12
[Install]
13
WantedBy=multi-user.target
14
EOF
15

16
sudo systemctl daemon-reload
17
sudo systemctl enable --now hdd-spindown.service
18
sudo systemctl status hdd-spindown.service --no-pager

展开收起

注意，设置 -S 时某些硬盘会被唤醒，所以这个服务开机执行一次就够了，不要平时反复重启。

记录硬盘什么时候被唤醒#

Linux 默认不会记录机械盘从 standby 变成 active/idle 的历史。

我做了一个简单脚本：每分钟读一次状态，只在状态变化时写入 journald。日志写在系统盘，不会写机械数据盘。

1
sudo tee /usr/local/sbin/hdd-power-watch >/dev/null <<'EOF'
2
#!/bin/bash
3

4
STATE_DIR=/run/hdd-power-watch
5
mkdir -p "$STATE_DIR"
6

7
for MOUNT_POINT in /mnt/hdd1 /mnt/hdd2; do
8
    PARTITION=$(findmnt -n -o SOURCE "$MOUNT_POINT" 2>/dev/null)
9
    [ -n "$PARTITION" ] || continue
10

11
    DISK="/dev/$(lsblk -ndo PKNAME "$PARTITION")"
12
    [ -b "$DISK" ] || continue
13

14
    STATE=$(
15
        /usr/sbin/hdparm -C "$DISK" 2>/dev/null |
16
        sed -n 's/.*drive state is:[[:space:]]*//p'
17
    )
18

19
    [ -n "$STATE" ] || STATE=unknown
20

21
    NAME=$(basename "$MOUNT_POINT")
22
    STATE_FILE="$STATE_DIR/$NAME"
23
    OLD_STATE=$(cat "$STATE_FILE" 2>/dev/null || echo unknown)
24

25
    if [ "$STATE" != "$OLD_STATE" ]; then
26
        logger -t hdd-power "$MOUNT_POINT ($DISK): $OLD_STATE -> $STATE"
27
        printf '%s\n' "$STATE" > "$STATE_FILE"
28
    fi
29
done
30
EOF
31

32
sudo chmod 755 /usr/local/sbin/hdd-power-watch

展开收起

service：

Terminal window

1
sudo tee /etc/systemd/system/hdd-power-watch.service >/dev/null <<'EOF'
2
[Unit]
3
Description=Record HDD power state changes
4
After=local-fs.target
5

6
[Service]
7
Type=oneshot
8
ExecStart=/usr/local/sbin/hdd-power-watch
9
EOF

timer：

Terminal window展开收起

1
sudo tee /etc/systemd/system/hdd-power-watch.timer >/dev/null <<'EOF'
2
[Unit]
3
Description=Check HDD power states every minute
4

5
[Timer]
6
OnBootSec=1min
7
OnUnitActiveSec=1min
8
AccuracySec=10s
9

10
[Install]
11
WantedBy=timers.target
12
EOF
13

14
sudo systemctl daemon-reload
15
sudo systemctl enable --now hdd-power-watch.timer
16
sudo systemctl start hdd-power-watch.service

展开收起

查看日志：

Terminal window

1
sudo journalctl -t hdd-power --no-pager

日志里大概会看到这些状态变化：

1
unknown -> active/idle      第一次建立基准状态
2
active/idle -> standby      硬盘进入休眠
3
standby -> active/idle      硬盘被唤醒

统计当天唤醒次数：

Terminal window

1
sudo journalctl -t hdd-power --since today --no-pager |
2
grep -c 'standby -> active/idle'

温度、SMART、风扇和前面板灯#

安装工具：

Terminal window

1
sudo apt install -y smartmontools lm-sensors

CPU、NVMe、内存和网卡温度：

Terminal window

1
sensors

机械盘温度：

Terminal window

1
sudo smartctl -A /dev/sdX

但普通 SMART 查询可能会唤醒休眠盘。休眠后用：

Terminal window

1
sudo smartctl -A -n standby /dev/sdX

如果磁盘正在休眠，它会直接退出，不会强行唤醒。

风扇方面，DXP4800 Plus 使用 IT8613E 监控芯片。安装社区 it87 驱动后，可以看到类似 fan2、fan3、pwm2、pwm3。

社区驱动：

1
https://github.com/IT-Kuny/UGREEN-DXP-FAN-NAS-Driver

我的处理方式是先观察转速，不急着用 pwmconfig 接管风扇。只要 CPU、SSD 和网卡温度正常，让主板自动控制通常更稳。

前面板灯可以用 LLLED：

1
https://github.com/BearHero520/LLLED

当时我遇到一个入口软链接路径问题：主程序通过 /usr/local/bin/LLLED 启动时，会把依赖目录算成 /usr/local/bin/scripts。

最后用包装脚本直接调用真实入口：

1
sudo rm -f /usr/local/bin/LLLED
2

3
sudo tee /usr/local/bin/LLLED >/dev/null <<'EOF'
4
#!/bin/bash
5
exec /opt/ugreen-led-controller/ugreen_led_controller.sh "$@"
6
EOF
7

8
sudo chmod 755 /usr/local/bin/LLLED
9
sudo LLLED status

最后的结构#

迁移完以后，这台 NAS 的逻辑就清楚多了：

1
系统 SSD
2
├── Debian
3
├── Docker 程序
4
├── systemd
5
└── 系统日志
6

7
应用 SSD
8
├── Docker engine
9
├── containerd
10
├── 数据库
11
├── 应用配置
12
├── 缩略图
13
└── 缓存
14

15
机械数据盘
16
├── 媒体
17
├── 归档
18
└── 低频数据

展开收起

机械盘不再承担 Docker 容器层、数据库、系统日志、缓存、缩略图和构建缓存。

它只放冷数据。这样它才更容易保持安静。

这次迁移后的几个判断#

Debian 不会天然比原 NAS 系统更伤盘。

硬盘并不知道上层跑的是绿联系统、Debian 还是 TrueNAS。真正影响机械盘的是温度、震动、电源质量、通电时间、读写负载、启停次数和后台访问频率。

频繁休眠也不一定比一直转更好。比较糟糕的是这种循环：

1
休眠
2
几分钟后被唤醒
3
再次休眠
4
又被后台扫描唤醒

所以休眠时间不要设得太短，还要记录实际唤醒次数。

旧盘恢复也要看数据价值。社区恢复工具值得尊重，也可能真的能救回数据。但恢复需要时间、额外磁盘、镜像空间和风险控制。数据越重要，越应该先做完整副本再研究；数据可以重新获取时，清空重建反而更理性。

最后，重装 Debian 的意义不是再堆一个 NAS 面板出来，而是只运行自己真正需要的服务。服务越少，后台行为越容易理解，机械盘也越容易安静。

这次最花时间的不是 Debian 安装器，也不是 Docker，而是弄清楚原系统对磁盘做了什么，以及迁移后怎样建立一套自己能看懂、能维护的存储逻辑。

我最后得到的不是一个功能更多的 NAS 系统，而是一台行为更可预测的 Linux 服务器：系统怎么更新，服务怎么跑，数据写到哪里，机械盘什么时候休眠，硬盘什么时候被唤醒，都能查清楚。

这就是我最终放弃原系统、选择 Debian 的原因。

使用 PowerDesigner 从 MySQL 反向工程生成物理数据模型并优化展示

Tue, 19 May 2026 00:00:00 GMT

把已有数据库结构反向导入 PowerDesigner 生成物理数据模型（PDM），再批量替换成中文名、按前缀自动分模块——这几步下来，模型就好读多了。

1. 新建 PDM 并连上数据库#

新建一个 Physical Data Model 文件，然后点菜单 Database → Configure Connections，左边选 Connection Profiles：

image

2. 配 MySQL 连接#

点左上角 + 新建 MySQL 连接：

image

填上主机、端口、用户名、密码和目标库名：

image

填完点 Test Connection 测通，没问题就保存。

3. 从数据库反向生成模型#

点 Database → Update Model from Database 打开选项窗口。

操作顺序：先点右侧 取消全选箭头（→|）清空默认勾选，再点左侧 选择数据库箭头（|←）选目标库，最后点 全选箭头（→|）选中所有表：

image

按上面步骤操作后，点确定就导入到 PDM 了：

image

4. 批量把英文名替换成中文注释#

PowerDesigner 默认显示英文名。如果数据库表字段已经写了中文 Comment，可以用脚本一次性替换过来。

路径：Tools → Execute Commands → Edit/Run Script

粘贴并运行以下脚本：

1
Option Explicit
2
ValidationMode = True
3
InteractiveMode = im_Batch
4

5
Dim mdl ' 当前模型
6

7
Set mdl = ActiveModel
8
If (mdl Is Nothing) Then
9
    MsgBox "当前没有打开的模型！"
10
ElseIf Not mdl.IsKindOf(PdPDM.cls_Model) Then
11
    MsgBox "当前模型不是物理数据模型（PDM）！"
12
Else
13
    ProcessFolder mdl
14
End If
15

16
Private Sub ProcessFolder(folder)
17
    On Error Resume Next
18
    Dim Tab
19
    For Each Tab In folder.Tables
20
        If Not Tab.IsShortcut Then
21
            If Tab.Comment <> "" Then Tab.Name = Tab.Comment
22
            Dim col
23
            For Each col In Tab.Columns
24
                If col.Comment <> "" Then col.Name = col.Comment
25
            Next
26
        End If
27
    Next
28

29
    Dim view
30
    For Each view In folder.Views
31
        If Not view.IsShortcut And view.Comment <> "" Then
32
            view.Name = view.Comment
33
        End If
34
    Next
35

36
    Dim f
37
    For Each f In folder.Packages
38
        If Not f.IsShortcut Then
39
            ProcessFolder f
40
        End If
41
    Next
42
End Sub

展开收起

跑完之后，模型里的表名、字段名、视图名就都换成中文了。

5. 按前缀自动分组并创建模块图表#

还能根据表名前缀（比如 act_、sys_）自动创建模块图表，把对应的表归进去。

路径一样：Tools → Execute Commands → Edit/Run Script，跑这个：

1
Option Explicit
2

3
Dim mdl, prefixMap, d, prefix, diagName
4
Dim tab, sym, symExists, diagram, tabCode
5
Dim createdCount, movedCount
6

7
Set mdl = ActiveModel
8

9
If mdl Is Nothing Then
10
    MsgBox "请在物理数据模型中运行此脚本！", vbExclamation
11
ElseIf mdl.ClassName <> "Physical Data Model" Then
12
    MsgBox "当前模型不是物理数据模型（PDM），请检查！", vbCritical
13
Else
14
    Set prefixMap = CreateObject("Scripting.Dictionary")
15
    prefixMap.Add "act_", "活动模块"
16
    prefixMap.Add "sys_", "系统模块"
17

18
    createdCount = 0
19
    movedCount = 0
20

21
    For Each prefix In prefixMap.Keys
22
        diagName = prefixMap(prefix)
23
        Set diagram = Nothing
24

25
        For Each d In mdl.PhysicalDiagrams
26
            If d.Name = diagName Then
27
                Set diagram = d
28
                Exit For
29
            End If
30
        Next
31

32
        If diagram Is Nothing Then
33
            Set diagram = mdl.PhysicalDiagrams.CreateNew()
34
            diagram.SetNameAndCode diagName, prefix & "diagram"
35
            createdCount = createdCount + 1
36
        End If
37

38
        For Each tab In mdl.Tables
39
            tabCode = LCase(tab.Code)
40
            If LCase(Left(tabCode, Len(prefix))) = LCase(prefix) Then
41
                symExists = False
42

43
                For Each sym In diagram.Symbols
44
                    If Not sym.Object Is Nothing Then
45
                        If sym.Object Is tab Then
46
                            symExists = True
47
                            Exit For
48
                        End If
49
                    End If
50
                Next
51

52
                If Not symExists Then
53
                    diagram.AttachObject(tab)
54
                    movedCount = movedCount + 1
55
                End If
56
            End If
57
        Next
58

59
        If Not diagram Is Nothing Then
60
            diagram.AutoLayout
61
        End If
62
    Next
63

64
    MsgBox "处理完成！" & vbCrLf & _
65
           "新创建模块图表：" & createdCount & " 个" & vbCrLf & _
66
           "新增表符号总数：" & movedCount & " 个", vbInformation
67
End If

展开收起

其他模块也一样，在 prefixMap.Add 里加一行就行：

1
prefixMap.Add "user_", "用户模块"
2
prefixMap.Add "order_", "订单模块"

执行后 PowerDesigner 会自动创建对应的模块图表，把匹配前缀的表归进去并自动布局：

image

总结#

跑完这五步，就能从 MySQL 反向生成 PDM、把英文名换成中文注释、按前缀自动分模块。接手上古系统或者做数据库文档标准化的时候特别好用，建议把脚本存下来，下个项目直接复用。