feat: 支持国际化时区 #3924 #3991

wuyzh39 · 2025-12-22T10:17:39Z

No description provided.

集成测试完善

定时任务触发接收时区、返回业务带时区信息

返回前端的秒级时间戳都转化成毫秒级

后台任务带上时间戳

改镜像时区，JVM时区采用运营时区

文件传输日志支持用户时区转化，mongodb存储结构改变及兼容改造

模版导入导出日志，添加用户管理saas web地址

文件日志，fix序列化报错

用户管理weburl

esb创建定时任务传时区

文件没问题时一开始不写入null

创建定时任务入口executeTime统一转化为秒级

redis缓存业务信息带上时区

从缓存中获取业务时区时，若为空，则在缓存中存空字符串

checkstyle问题修复

补充单测，覆盖蓝鲸统一的时区列表

jsonwan · 2025-12-25T01:46:34Z

support-files/kubernetes/charts/bk-job/values.yaml

 ## 蓝鲸 cmdb url
 bkCmdbUrl: "http://cmdb.example.com"
+# 用户管理SaaS web页面url
+bkUserSaasWebUrl: "http://bk-user.example.com"


命名建议调整为bkUserUrl，与helm-charts仓库中的example/address.yaml中运维预定义的值保持一致。

jsonwan · 2025-12-25T08:23:55Z

support-files/kubernetes/charts/bk-job/values.yaml

+timezone:
+  default:
+    # 默认展示时区（前端使用，当业务和个人都没有配置时区时使用）
+    display: "Asia/Shanghai"


这个值没有用到，是否可以去除？

WebGlobalSettingsQueryResourceImpl中getDefaultDisplayTimezone用到了

jsonwan · 2025-12-25T08:24:53Z

support-files/kubernetes/charts/bk-job/values.yaml

    # 服务后台日志可使用的最大磁盘空间（超出后将清理最旧的日志文件，但每类日志文件至少保留一个），单位支持B、KB、MB、GB、TB、PB，默认40GB
    maxVolume: 40GB
+  # 日志时区（用于日志输出的时间格式）
+  timezone : "Asia/Shanghai"


这个值没有用到，是否可以去除？

jsonwan · 2025-12-25T09:00:36Z

support-files/kubernetes/images/backend/backend.Dockerfile

-RUN ln -snf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \
-    echo 'Asia/Shanghai' > /etc/timezone && \
+RUN ln -snf /usr/share/zoneinfo/UTC /etc/localtime && \
+    echo 'UTC' > /etc/timezone && \


时区相关的配置建议都放在os.Dockerfile里面，避免重复

jsonwan · 2025-12-25T09:02:51Z

support-files/kubernetes/images/migration/migration.Dockerfile

-RUN ln -snf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \
-    echo 'Asia/Shanghai' > /etc/timezone && \
+RUN ln -snf /usr/share/zoneinfo/UTC /etc/localtime && \
+    echo 'UTC' > /etc/timezone && \


时区相关的配置建议都放在os.Dockerfile里面，避免重复

jsonwan · 2025-12-25T09:03:03Z

support-files/kubernetes/images/startup-controller/startupController.Dockerfile

-RUN ln -snf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \
-    echo 'Asia/Shanghai' > /etc/timezone && \
+RUN ln -snf /usr/share/zoneinfo/UTC /etc/localtime && \
+    echo 'UTC' > /etc/timezone && \


时区相关的配置建议都放在os.Dockerfile里面，避免重复

jsonwan · 2025-12-25T09:11:03Z

...ackend/commons/common/src/main/java/com/tencent/bk/job/common/constant/JobCommonHeaders.java

+    /**
+     * 用户时区
+     */
+    String BK_USER_TIMEZONE = "X-Bk-User-Timezone";


如果这个Header是Job专用的话，建议改为：X-Bk-Job-User-Timezone

jsonwan · 2025-12-25T09:38:18Z

...mmons/common/src/main/java/com/tencent/bk/job/common/util/json/SecondToMillisSerializer.java

+import java.util.List;
+
+/**
+ * 将秒级时间戳转换为毫秒级时间戳的 Json 序列化器


建议说明一下，只支持Long和List类型，避免误用导致难以排查的问题。

jsonwan · 2025-12-25T09:39:04Z

...mmons/common/src/main/java/com/tencent/bk/job/common/util/json/SecondToMillisSerializer.java

+                }
+            }
+            gen.writeEndArray();
+        }


else条件建议打一条日志出来，说明遇到了不支持的类型。

jsonwan · 2025-12-25T10:13:39Z

...b/api-job-crontab/src/main/java/com/tencent/bk/job/crontab/model/CronJobCreateUpdateReq.java

    /**
     * 单次执行的指定执行时间
     * <p>
     * 不可与 cronExpression 同时为空


建议增加说明：要求前端传的是ms

jsonwan · 2025-12-25T10:15:37Z

...d/commons/common/src/main/java/com/tencent/bk/job/common/util/json/ToSecondDeserializer.java

+@Slf4j
+public class ToSecondDeserializer extends JsonDeserializer<Object> {
+
+    private static final long MAX_SECOND_TIMESTAMP = 9999999999L;


建议改成9_999_999_999L这种含下划线的写法方便读取。

jsonwan · 2025-12-25T11:48:50Z

...mmon-i18n/src/main/java/com/tencent/bk/job/common/i18n/config/DefaultTimezoneProperties.java

+     *
+     * @return 运营时区的 ZoneId
+     */
+    public ZoneId safelyGetOperationZoneId() {


未使用的方法是否可以删除？

jsonwan · 2025-12-25T11:52:20Z

...mmon-i18n/src/main/java/com/tencent/bk/job/common/i18n/config/DefaultTimezoneProperties.java

+    /**
+     * 运营时区
+     */
+    private String operation = TimeZoneConstants.DEFAULT_ZONE_NAME_CN;


这个变量没有在别的类中被使用，需要看下是否能够和display合并为一个。

配置中区分display和operation，所以这个类中同样都存在这两个。

搜索了下，operation这个字段是在@scheduled注解中被使用到了，建议注释中说明下。

jsonwan · 2025-12-25T15:25:19Z

...ob-crontab/src/main/java/com/tencent/bk/job/crontab/api/web/impl/WebCronJobResourceImpl.java

+     * @param appId 业务ID
+     * @param cronJobCreateUpdateReq 请求体
+     */
+    private void processExecuteTimeZone(Long appId, CronJobCreateUpdateReq cronJobCreateUpdateReq) {


这里应该是个兼容逻辑，发布完成后新版本Web接口中时区字段就是一个必须传的字段，建议用兼容注解标记后续处理。

jsonwan · 2025-12-26T02:25:01Z

...c/main/java/com/tencent/bk/job/manage/api/common/constants/globalsetting/RelatedUrlKeys.java

    // 登录地址
    public static final String KEY_BK_LOGIN_URL = "BK_LOGIN_URL";
+    // 用户管理SaaS Web页面根地址
+    public static final String KEY_BK_USER_SAAS_WEB_ROOT_URL = "BK_USER_SAAS_WEB_ROOT_URL";


用户管理相关的配置项/常量里面建议把SAAS字样去掉，如果它将来不再以Saas形态部署，这个Saas就会变得奇怪

jsonwan · 2025-12-26T03:02:20Z

.../service-job-logsvr/src/main/java/com/tencent/bk/job/logsvr/service/impl/LogServiceImpl.java

+        } else if (StringUtils.isNotEmpty(fileTaskLog.getContent())) {
+            // 老版本兼容：若writeContentList为空，说明是老版本的请求，直接push字符串（内容中已包含时间）
+            // 版本发布后可删除
            pushDBObject.append(FileTaskLogDocField.CONTENT_LIST, fileTaskLog.getContent());


用于发布过程兼容的代码建议抽取到单独的方法中并适当打印日志（注意控制频率），便于后续删除时检查是否有被使用，用到老字段的其他位置也都检查处理下。

jsonwan · 2025-12-26T03:19:21Z

...common-web/src/main/java/com/tencent/bk/job/common/web/interceptor/JobCommonInterceptor.java

+                zoneId = ZoneId.of(userTimeZone);
+                log.debug("Set user timezone from header: {}", userTimeZone);
+            } catch (Exception e) {
+                // 如果用户时区不合法，使用默认时区


这个逻辑可能有问题，用户/业务时区未配置时可以使用默认时区，如果用户设置了时区但是取值不正确，这时使用默认时区可能不符合用户预期，报错出来可能更恰当。

现在改为抛异常，返回400

jsonwan · 2025-12-26T03:26:59Z

...ntab/src/main/java/com/tencent/bk/job/crontab/model/esb/v3/request/EsbSaveCronV3Request.java

+     * 默认为 Asia/Shanghai
+     */
+    @JsonProperty("execute_time_zone")
+    private String executeTimeZone;


接口文档需要相应修改。

jsonwan · 2025-12-26T03:27:05Z

...crontab/src/main/java/com/tencent/bk/job/crontab/model/esb/v3/response/EsbCronInfoV3DTO.java

+     */
+    @JsonProperty("execute_time_zone")
+    @JsonPropertyDescription("Execute time zone")
+    private String executeTimeZone;


接口文档需要相应修改。

jsonwan · 2025-12-26T03:28:25Z

...ckup/service-job-backup/src/main/java/com/tencent/bk/job/backup/archive/ArchiveCronJobs.java

-    @Scheduled(cron = "${job.backup.archive.execute.cron: 0 1 * * * *}")
+    @Scheduled(
+        cron = "${job.backup.archive.execute.cron: 0 1 * * * *}",
+        zone = "${timezone.default.operation:Asia/Shanghai}"


重复的次数比较多，看看能否使用自定义注解消除重复。

可以使用自定义注解，但我觉得这在原生的@schedule中指定zone应该挺合理的吧

不是指完全自己实现注解的解析逻辑，是用更高层的注解把@scheduled包装一层，消除时区字段重复的默认值指定，可参考@JobTransactional。

已将Scheduled全部换为包装后的ScheduledOnOperationTimeZone

jsonwan · 2025-12-26T03:41:12Z

...i-job-manage/src/main/java/com/tencent/bk/job/manage/AbstractLocalCacheCommonAppService.java

            );

+    private final LoadingCache<Long, String> appIdTimeZoneCache =
+        CacheBuilder.newBuilder().maximumSize(100_000).expireAfterWrite(1, TimeUnit.HOURS)


缓存容量建议500，覆盖活跃的业务即可。

jsonwan · 2025-12-26T03:44:46Z

...b-manage/src/main/java/com/tencent/bk/job/manage/api/web/WebGlobalSettingsQueryResource.java

+
+    @ApiOperation(value = "获取默认展示时区", produces = "application/json")
+    @GetMapping("/defaultDisplayTimezone")
+    Response<String> getDefaultDisplayTimezone(


展示时区的实现上需要看下能否直接使用运营时区。

后续可能会有平台的运维和用户不是一波的情况，可以先保留

日志里面并没有打时区，因为现在启动的时候在JVM参数中加上了运营时区，所以打出的日志是运营时区的时间。

这样可以不需要修改日志平台中的清洗配置

jsonwan

一些小问题需要处理下，另外需要看下日志时区的实现是否漏了。

处理review

…zone

jsonwan · 2026-01-04T07:32:03Z

docs/apidoc/bk-api-gateway/v3/zh/save_cron.md

+| name              | string | 否  | 定时作业名称，新建时必填，修改时选填                                                                |
+| expression        | string | 否  | 定时任务 crontab 的定时规则，新建时必填，修改时选填，各字段含义为：分 时 日 月 周，如: 0/5 * * * * 表示每5分钟执行一次，注意：不支持? |
+| execute_time      | long   | 否  | 定时任务单次执行的执行时间，Unix时间戳，新建定时任务时不可与expression同时为空                                    |
+| execute_time_zone | string | 否  | 定时任务在哪个时区下的定时表达式或执行时间触发，不传默认采用业务时区，若是业务未配置业务时区，则默认在Asia/Shanghai的时间触发             |


这里建议要给一个时区ID的标准取值范围或者一个权威的标准文件地址出来，比如我想填硅谷所在的时区，这个值应该填什么，或者我应该去哪里找要填写的值，填写了之后才会被Job系统认识。

jsonwan

评论已回复，几个小问题需要处理下。

处理review

添加iam跳转地址

wuyzh39 added 20 commits November 27, 2025 20:34

feat: 支持国际化时区 TencentBlueKing#3924

84b0126

feat: 支持国际化时区 TencentBlueKing#3924

cd61190

集成测试完善

feat: 支持国际化时区 TencentBlueKing#3924

473512c

feat: 支持国际化时区 TencentBlueKing#3924

e601b05

定时任务触发接收时区、返回业务带时区信息

feat: 支持国际化时区 TencentBlueKing#3924

789c493

返回前端的秒级时间戳都转化成毫秒级

feat: 支持国际化时区 TencentBlueKing#3924

f8c79df

后台任务带上时间戳

feat: 支持国际化时区 TencentBlueKing#3924

5bcc0a5

改镜像时区，JVM时区采用运营时区

feat: 支持国际化时区 TencentBlueKing#3924

f86e4d8

feat: 支持国际化时区 TencentBlueKing#3924

3d2a42e

feat: 支持国际化时区 TencentBlueKing#3924

380b6aa

文件传输日志支持用户时区转化，mongodb存储结构改变及兼容改造

feat: 支持国际化时区 TencentBlueKing#3924

4110361

模版导入导出日志，添加用户管理saas web地址

feat: 支持国际化时区 TencentBlueKing#3924

44088f3

文件日志，fix序列化报错

feat: 支持国际化时区 TencentBlueKing#3924

7c4413f

用户管理weburl

feat: 支持国际化时区 TencentBlueKing#3924

90a0a8f

esb创建定时任务传时区

feat: 支持国际化时区 TencentBlueKing#3924

e254692

文件没问题时一开始不写入null

feat: 支持国际化时区 TencentBlueKing#3924

7796513

创建定时任务入口executeTime统一转化为秒级

feat: 支持国际化时区 TencentBlueKing#3924

db5b41f

redis缓存业务信息带上时区

feat: 支持国际化时区 TencentBlueKing#3924

bf1e8f0

从缓存中获取业务时区时，若为空，则在缓存中存空字符串

feat: 支持国际化时区 TencentBlueKing#3924

22d9b35

checkstyle问题修复

feat: 支持国际化时区 TencentBlueKing#3924

25c5ed8

补充单测，覆盖蓝鲸统一的时区列表

wuyzh39 closed this Dec 23, 2025

wuyzh39 reopened this Dec 23, 2025

jsonwan reviewed Dec 25, 2025

View reviewed changes

jsonwan reviewed Dec 26, 2025

View reviewed changes

jsonwan requested changes Dec 26, 2025

View reviewed changes

wuyzh39 added 4 commits December 26, 2025 18:04

feat: 支持国际化时区 TencentBlueKing#3924

5961f2e

处理review

feat: 支持国际化时区 TencentBlueKing#3924

6d10d8b

处理review

Merge remote-tracking branch 'upstream/feat/tenant' into github_feat/…

bd56caa

…zone

Merge branch master into github_feat/zone

2aeca7f

jsonwan reviewed Jan 4, 2026

View reviewed changes

jsonwan requested changes Jan 4, 2026

View reviewed changes

feat: 支持国际化时区 TencentBlueKing#3924

2c32af3

处理review

jsonwan approved these changes Jan 5, 2026

View reviewed changes

wuyzh39 added 3 commits January 14, 2026 11:15

feat: 支持国际化时区 TencentBlueKing#3924

378b1b0

feat: 支持国际化时区 TencentBlueKing#3924

d441032

feat: 支持国际化时区 TencentBlueKing#3924

26359b4

添加iam跳转地址

feat: 支持国际化时区 #3924 #3991

Are you sure you want to change the base?

feat: 支持国际化时区 #3924 #3991

Uh oh!

Conversation

wuyzh39 commented Dec 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

jsonwan Dec 26, 2025 •

edited

Loading