简介面向阿里云专有云企业版 V3.12.0 环境下的大数据开发、运维与数据治理人员这份 DataWorks 用户指南文档版本 20200706提供从控制台登录、工作空间创建到数据集成、开发、治理、服务与安全的操作参考也适合需要快速熟悉平台模块划分和权限管理的团队作为案头手册。资源包共 1 个 PDF 文件大小约 32.03MB内容按入门概述、建表上传数据、创建业务流程与同步任务、设置周期依赖、运行排错等章节组织并覆盖数据资产、元数据、质量监控、数据 API、角色权限、脱敏与审计等主题。已有 187 人学习读者可据目录定位具体功能结合警示级别、命令行与参数约定理解操作边界并借助法律声明和版本更新说明规范文档使用。1. 专有云 DataWorks V3.12.0 用户指南先啃哪几章决定你多久能跑通第一条链路控制台地址是一串内网 IP 加端口页面没有注册入口账号得找管理员开——第一次接手专有云企业版 DataWorks 的人基本都是这个开局。手上这份 V3.12.0、文档版本 20200706 的用户指南对应的正是这种私有化部署形态它不讲公有云的开通流程开门就是登录控制台、建工作空间后面铺开数据集成三十多个读写插件、数据开发节点类型、整库迁移和数据治理。这份 PDF 回答的不是“DataWorks 是什么”而是“内网这套环境里哪几个参数必须照文档填、填错会怎样”。它适合三类人刚接手平台的数仓开发、要做异构数据源同步的 ETL 工程师、负责周期任务排障的运维。下面按“跑通一条链路 → 配好一个同步作业 → 批量搬一批表 → 避开几类翻车 → 上线前再查一遍”的顺序往下拆。2. 登录到第一条同步任务跑通快速入门五步的顺序与参数快速入门在整份指南里只占六页却是唯一一条把“工作空间 → 建表 → 传数据 → 业务流程 → 同步任务 → 周期依赖 → 运行排错”串成闭环的线。跳过它直接翻数据集成那一章最常见的翻车是节点建好了挂不进业务流程或者实例状态一片绿、目标表里一条数据没有。这一章按指南给的顺序把每一步真正要填的参数抠出来。2.1 控制台与工作空间动手前先确认三件事登录之前先问清楚三件事能省掉后面一半的沟通成本。第一是账号体系专有云环境的账号通常由内部统一认证接入控制台只做权限映射没有自助注册第二是工作空间模式简单模式只有一套环境标准模式拆成开发和生产两套决定了你后面能不能做“先开发后发布”第三是计算引擎与调度资源组的绑定关系工作空间必须挂到一个已存在的 MaxCompute 项目实例上否则建表这一步直接没有可选目标。登录后进入工作空间列表点新建表单里真正影响后续的字段大概这几个字段填什么填错的后果工作空间名称英文数字全局唯一后续改名要走迁移节点引用会断模式简单 / 标准选简单模式就没有开发生产隔离测试数据直接进生产表计算引擎实例已绑定的 MaxCompute 项目为空时数据开发里建不了 ODPS SQL 节点调度资源组平台预置或自建未绑定则周期任务无法下发实例责任人实际负责人账号告警和审批会落到挂名账号上没人处理工作空间建完不要急着写 SQL先在工作空间配置里把成员和角色过一遍。指南在数据安全部分列了角色权限管理实操里最常见的问题是给开发同学开了“运维”角色结果他能重跑生产实例、能改调度时间出了问题定位不到是谁动的。2.2 建表、传数据、建业务流程最小闭环怎么搭最小闭环建议就用一张小表跑通别一上来接生产库。在数据开发里新建 MaxCompute 表DDL 直接写-- 测试用订单明细表分区字段必须放在表结构最后 CREATE TABLE IF NOT EXISTS ods_order_detail ( order_id BIGINT COMMENT 订单ID, user_id BIGINT COMMENT 用户ID, pay_amount DECIMAL(18,2) COMMENT 支付金额, gmt_create STRING COMMENT 创建时间 ) COMMENT 订单明细测试表 PARTITIONED BY (dt STRING COMMENT 日期分区格式 yyyyMMdd);这段 DDL 有三个点值得留意。分区字段dt必须写在PARTITIONED BY里而不是普通列里写错了建表能过但后续INSERT OVERWRITE ... PARTITION会报字段数不匹配。金额用DECIMAL(18,2)而不是DOUBLE因为下游做汇总时浮点误差会累积对账阶段很难解释。COMMENT不是可选项元数据管理和血缘页面展示的都是这里的中文名全表裸字段后期治理成本很高。建完表上传数据。指南的做法是在表管理里选导入指定本地 CSV 或 TXT、分隔符、是否跳过首行、编码。内网环境常见做法是先把文件放到跳板机上再通过平台的上传入口传几十 MB 以内问题不大超过就往 OSS 或 HDFS 里放用数据集成往里灌。然后是业务流程。数据开发里新建一个业务流程把刚建的表和一个 ODPS SQL 节点挂进去-- 节点名dwd_order_summary_di -- 调度参数已配置dt${bizdate} INSERT OVERWRITE TABLE dwd_order_summary PARTITION (dt${bizdate}) SELECT user_id, COUNT(1) AS order_cnt, SUM(pay_amount) AS pay_amt FROM ods_order_detail WHERE dt ${bizdate} GROUP BY user_id;${bizdate}是调度系统在实例生成时替换的变量默认取业务日期格式yyyyMMdd。本地点“运行”时它替换成你手填的参数值走调度时由系统按周期算这两个路径的结果经常不一样所以第一次一定要两边都跑一次对比。INSERT OVERWRITE配合分区重跑是幂等的如果写成INSERT INTO一次重跑就多一份数据这是我在早期项目里交过学费的地方。节点写完必须在右侧调度配置里设周期没设周期的节点只能手动跑不会进运维中心。2.3 周期与依赖定时时间、调度周期、依赖上一周期怎么填调度配置这一块是新手最容易糊弄过去、后期最容易出问题的地方。指南把它单独拎出来讲是因为参数之间的耦合比看上去强。参数典型取值说明调度周期日 / 小时 / 分钟 / 周 / 月决定实例生成粒度日调度每天生成一个实例定时时间00:00 或业务要求的时点实例最早可运行时间不是保证在这个点跑完依赖上一周期勾选勾上后当天实例要等前一天实例成功才启动优先级1~8资源紧张时决定排队顺序超时时间按任务耗时设超时后实例置为失败并告警出错自动重跑勾选 次数 间隔网络抖动类失败靠它兜底关键在“依赖上一周期”。日调度默认实例时间是 00:00如果你的上游是前一天 23:30 才跑完的下游在 00:00 就已经开始跑了读到的是上游还没写完的数据或者空分区。勾上依赖上一周期等于告诉系统“等昨天的我自己成功了你再动”。这一条在指南的“设置周期和依赖”小节里写得很直白但实际项目里十个调度事故有六个跟它有关。还有一点跨业务流程的依赖不要靠定时时间凑。A 业务流程产出表、B 业务流程消费表正确做法是在 B 的节点里配置上游依赖指向 A 的产出节点而不是把 B 的定时时间往后推半小时。时间差是玄学依赖关系是确定性的。2.4 运行及排错先看哪三个地方实例跑挂了别急着改代码按顺序看三个地方。第一看运维中心的周期实例列表实例状态分为等待、运行、成功、失败等待状态点进去能看到它在等哪些上游很多时候不是你的问题。第二看实例详情里的运行日志日志分 Reader 和 Writer 两段各自会打印读取条数、写入条数、脏数据条数和总耗时四个数字一对照问题类型基本就定了读 0 写 0 是源端没数据或条件写错读 N 写 0 是目标端权限或表结构不匹配读 N 写 MMN是脏数据被过滤。第三看任务本身的调度参数替换结果在实例详情里能看到${bizdate}实际被换成了什么值替换错了后面全错。3. 数据集成 Reader/Writer一个 MySQL 到 MaxCompute 的脚本作业拆到底数据集成这一章在指南里篇幅最长三十多个数据源、二十多个 Reader、二十多个 Writer一个个看会看晕。实际工作中 80% 的同步作业就那么几种组合关系库到 MaxCompute、日志到 MaxCompute、MaxCompute 到关系库。把一组配置吃透剩下的都是换插件名和换连接串。3.1 数据源连通性测试与开发/生产隔离配数据源之前先做连通性测试这一步在指南的 4.3 节。测试走的是数据集成资源组的网络不是你的办公网所以本地用客户端能连上、平台测不通是很正常的现象别急着怀疑密码。测不通先查三件事资源组所在网段到数据库端口是否放通、数据库账号是否限制了来源 IP、JDBC URL 里的库名和参数是否和客户端里的一致。指南 4.4.2 单独讲了数据源隔离标准模式下开发环境和生产环境可以配不同的数据源。这个功能看着不起眼实际是保命的开发环境的数据源指向测试库生产环境指向生产库同一个作业发布上线时连接串自动切换。反过来如果你在开发环境配的就是生产库地址那所有测试跑出来的脏数据都落在生产表里而且因为开发环境通常不开严格的审批出问题很难追溯。我一般会强制要求开发环境数据源名字里带_dev后缀肉眼能区分。数据源权限也要单独配。指南 4.4.4 讲了数据源权限管理配好数据源不等于所有人都能用还要在工作空间成员里授权。常见坑是数据源建好了、作业也写了运行时报“无权限访问数据源”回头补授权又得等审批。3.2 脚本模式完整 JSON 与逐字段说明向导模式点几下就能生成作业但一旦涉及增量条件、字段裁剪、分片键就必须切脚本模式。下面这个例子是从 MySQL 抽订单表到 MaxCompute 对应的分区表每天跑一次{ type: job, version: 1.0, configuration: { setting: { speed: { channel: 3, throttle: false }, errorLimit: { record: 100 } }, reader: { plugin: mysql, parameter: { username: etl_reader, password: ******, column: [order_id, user_id, pay_amount, gmt_create], splitPk: order_id, fetchSize: 1024, where: gmt_create ${bizdate} AND gmt_create date_add(${bizdate}, interval 1 day), connection: [ { table: [order_detail], jdbcUrl: [jdbc:mysql://10.0.0.11:3306/shop] } ] } }, writer: { plugin: odps, parameter: { project: dw_prod, table: ods_order_detail, partition: dt${bizdate}, truncate: true, accessId: ******, accessKey: ******, odpsServer: http://10.0.0.21:8080/api, tunnelServer: http://10.0.0.21:8081 } } } }逐段说。setting.speed.channel是并发通道数直接决定同时开几个连接拉数默认值偏保守小表够用大表要往上调但调之前先确认源库扛得住。throttle打开后可以按字节或记录数限速专有云环境里源库往往是共享的白天抽数不限速会被 DBA 找上门。errorLimit.record是脏数据容忍条数设 0 表示一条脏数据就整批失败设 100 表示前 100 条脏数据跳过并记录第 101 条触发失败。Reader 侧splitPk是做并发切分的字段必须选数值型或单调递增的主键类字段选了字符串或者分布极不均匀的字段切出来的分片大小差几十倍三个通道里只有一个在干活。fetchSize控制每次从结果集取多少行太小网络往返多太大会撑内存1024 到 4096 之间比较稳。where里写了增量条件注意日期函数用的是数据库方言MySQL 和 Oracle 写法不同照抄会报语法错。Writer 侧partition指定写入分区dt${bizdate}会随调度替换。truncate: true表示写入前清空目标分区配合INSERT OVERWRITE语义保证重跑幂等。odpsServer和tunnelServer是专有云环境特有的走的是内网地址公有云版本里这两个参数通常不填直接照公有云文档抄就会连不上。3.3 向导模式与脚本模式的边界什么时候必须切脚本向导模式省事但它的能力边界很清楚单表到单表、字段一一对应、无复杂过滤条件、无动态分区。一旦碰到下面任意一条就必须切脚本场景向导模式脚本模式增量抽取带时间条件支持有限where 自由写分片键自定义部分支持splitPk 任意指定多表合并到一个目标表不支持connection 里配多个 table动态分区 / 分区字段来自源表不支持支持前置/后置 SQL支持preSql / postSql写入模式精细控制有限writeMode 可指定切脚本不是重写向导模式配好后可以转成脚本再改转完记得把连接串里的密码字段处理掉脚本里是明文的虽然平台会做脱敏展示但导出作业配置时能看到原值这一点在交付文档时要留意。4. 整库迁移与同步优化几十张表批量搬的并发、限速与校验单表同步跑通了下一个问题往往是“这几十张表怎么搬”。指南的 4.6 节专门讲整库迁移覆盖 MySQL 和 Oracle 两种来源配置思路一样都是先选库、再选表、生成一批同步任务。4.1 整库迁移的前置条件与表名过滤整库迁移不是无脑全选。前置条件至少有四条源库账号要有全库读权限或者目标表的读权限目标端的 MaxCompute 项目要提前建好并且表名映射规则定下来源表的主键或唯一键要确认没有主键的表做增量同步会很麻烦字符集和时区要对齐源库是 UTC、目标端按东八区解释时间字段会整体偏八小时。表名过滤在整库迁移的配置页里是正则或通配符形式。生产库里通常混着业务表、临时表、备份表全选会把xxx_bak_20200301这种也搬过去。我一般先按^[a-z]_[a-z_]$这类规则粗筛再人工过一遍列表把日志表、流水表单独处理——流水表动辄上亿行跟配置表混在一批里跑整体进度会被拖死。迁移任务的生成方式有两种一种是平台按表批量生成多个同步任务每个任务对应一张表调度周期统一另一种是生成一个任务内部循环多表。前者好在单表失败不影响其他表重跑粒度细后者好在任务数量少调度压力小。表多的时候选前者表少且逻辑一致的时候选后者。4.2 并发通道、限速、脏数据阈值三个旋钮同步作业跑得慢或者跑挂了八成是这三个参数没调对。并发通道channel决定并行度。经验值是先看源库的 CPU 和 IO 余量再定通道数一般 3 到 8 之间超过 8 收益递减明显因为瓶颈往往在源库单表扫描上。分片键选得不好通道开再多也是浪费前面提过。限速throttle在专有云环境下几乎是必开的。指南的“优化配置”小节给了按字节和按记录数两种限速方式白天抽数按 5~10 MB/s 限夜间窗口可以放开。不限速的后果不是任务失败是业务库的慢查询告警一起响然后 DBA 找过来这属于可预见但经常被忽略的坑。脏数据阈值errorLimit.record要按场景分。配置表、维表这种数据质量高的设 0出问题就要停下来看日志表、埋点表这种天生有脏数据的设一个几百到几千的容忍值同时把脏数据记录下来事后抽样看是什么类型的脏数据。最怕的是为了“让任务跑过去”直接把阈值设成 1000000等于关掉了数据质量的第一道闸门。4.3 迁移后校验行数、抽样、字段类型三件事迁移完成不等于迁移正确。校验分三层。第一层是行数对账源端按天统计COUNT(1)目标端按分区统计两边差值超过千分之一就要查差值通常是 where 条件边界写错或者时区偏移导致跨天数据漏抽。第二层是抽样比对随机取 100 行主键两端按主键查出来逐字段对比重点看金额、时间、枚举字段这三类最容易在类型转换时失真。第三层是字段类型核对源库的DECIMAL(18,4)迁到目标端被建成DECIMAL(18,2)小数位直接截断行数一条不差但数据是错的这种问题只有看元数据才能发现。一个稳妥的做法是把这三层校验也做成一个节点挂在迁移任务下游跑完自动输出对账报告到一张结果表里第二天早上看表就行不用逐个人工查。5. 避坑与排查四条在内网环境里最容易翻车的记录这一节记的都是实打实踩过的现象、原因、解决按顺序写遇到类似情况可以直接对着看。5.1 调度参数没替换数据全落到默认分区现象任务每天定时跑日志显示成功写入条数也正常但目标表只有一个分区里有数据而且是最早那天的日期。原因节点里写的分区值不是${bizdate}而是硬编码的20200101或者写了${bizdate}但调度配置里没定义这个参数系统按空值处理落到了默认分区。解决在调度配置的参数面板里显式定义bizdate$bizdate然后在实例详情里看参数替换后的实际值每次改完节点都手动触发一次并对着目标表分区确认。5.2 连通性测试通过了任务照样连不上现象数据源页面点“测试连通性”显示成功同一个数据源在作业里运行却报连接超时。原因测试连通性走的是数据集成资源组的网络出口而作业调度执行时用的可能是另一个资源组或调度集群网络策略没覆盖到。也可能是数据源隔离没配开发环境的数据源配了生产环境那一栏是空的发布上线后作业找不到连接串。解决先确认作业实际使用的资源组在资源组维度再测一次连通性再检查开发环境和生产环境的数据源是否都配齐标准模式下这两份是独立的。5.3 脏数据阈值设成 0一条脏数据拖垮整批现象一个跑了三个月的同步任务某天突然失败日志里只有一行“脏数据条数超过限制”具体是哪条数据、什么原因看不到。原因errorLimit.record设为 0且没有开启脏数据记录。源库那边上游改了个字段格式或者某个字段开始出现空值整批作业直接中断。解决把record调到一个合理容忍值同时确保脏数据能被记录和查询另外在同步任务下游挂一个数据质量检查节点比守在日志里翻要靠谱得多。这类问题一旦发生在凌晨救火成本远高于提前配置。5.4 分片键选错三个并发只有一个在干活现象channel设成 6任务实际耗时和channel1差不多日志里各个通道的读取行数差了几十倍。原因splitPk选了一个分布极不均匀的字段比如状态位、地区编码切出来的分片有的几百万行、有的几百行最后整体耗时由最大的那个分片决定。解决换成数值型自增主键或订单号这类高基数字段如果表本身没有合适的切分字段宁可把channel降到 2~3也别用错误的键硬切并发不是越多越好。5.5 开发环境跑得好好的发布到生产就报权限错误现象作业在开发环境测试通过点了发布生产实例失败报“表不存在”或“无权限”。原因开发环境和生产环境的 MaxCompute 项目是两套开发环境里有你手动建的表生产环境里没有或者生产项目的角色没授到你这个账号上开发环境宽松、生产严格。解决发布前把节点里的表名、项目名、数据源全部过一遍确认都指向生产侧标准模式下走发布流程时会有变更对比页那一页要真看不要直接点下一步。6. 上线前的三个检查动作SQL 规范、版本对比与节点选型把作业从“能跑”推到“敢按周期挂着跑”我一般只做三件事花不了二十分钟但能把大部分事故挡在前面。第一件是过 SQL 规范。指南 5.2 节给了编码原则落地成可执行的检查就三条SELECT 不写*字段全部列出来表结构一变不会连带炸掉下游WHERE 里必须带分区字段否则全表扫描一个作业能把整天的资源吃光表别名统一用有意义的前缀多表关联时a.b.这种别名在几十行 SQL 里根本对不上号。对账类 SQL 再加一条金额字段显式写ROUND避免两边精度规则不同导致的对不平。第二件是版本对比。数据开发里的节点有版本管理每次保存生成一个版本发布前把当前版本和线上版本拉出来对比。这个动作的价值不在于看改了什么而在于确认“我只改了想改的那部分”——复制粘贴导致的多余空格、误删的一行注释、被顺手改掉的调度参数都会在这一步现形。血缘页面也顺手看一眼确认下游节点列表和你预期的一致避免改了一个公共节点结果影响了十几个下游。第三件是节点选型复核。同样一段逻辑用 ODPS SQL、PyODPS、ODPS Spark 写资源占用和容错能力差很多。纯 SQL 能表达的就用 ODPS SQL调度开销最小、日志最好读需要调外部接口、做复杂字符串处理的上 PyODPS但要控制单实例内存数据量上亿且需要多轮迭代的才考虑 Spark否则启动开销比计算时间还长。Shell 节点只做调度编排不要在里面塞业务逻辑出问题时日志会碎成好几段排查体验极差。最后补一个习惯每次发布前把调度参数、数据源、目标表分区这三个东西打印在一张纸上对一遍看起来土但它救我的次数比任何监控都多。有一次我把生产作业的分区从${bizdate}改成了${bizdate-1}测试环境跑得漂漂亮亮是因为测试数据本来就有两天上线后第一天才发现整个数仓的分区整体滞后一天回溯补数花了整整一个周末。从那以后我每次改分区参数都强制走一遍“测试环境跑一次 实例详情对参数 目标表分区确认”这条线不再凭感觉。希望帮到你。本文还有配套的精品资源点击获取