C SDK:恢复完整安装包上传
本页内容
保存上传检查点,在网络中断或进程重启后继续原任务,并确认最终版本。
适用场景
需要完整上传 IPA 或 APK,并在断网或进程重启后继续时,使用 C 上传会话。平台选择传输服务,SDK 处理任务创建、分片和确认;您的程序持久保存恢复记录。
本教程先运行源码包中的完整上传 CLI。需要自行集成时,再将同样的保存回调接入自己的数据库或私有文件。
前提条件
- 已完成 C SDK 入门,持有长期 AccessKey,并按产品授予
enterprise:UploadVersions或distribution:UploadVersions。 - 准备已有业务应用 ID、原始安装包与整包 SHA-256。新应用先完成应用预留;上传助手不创建应用或购买服务。
- 首次请求前持久保存文件身份和本次创建幂等键。恢复时继续原文件与原记录,不重新计算另一份文件覆盖原摘要。
- 准备私有状态文件和允许访问的 HTTPS 文件传输域名。状态文件不含 AccessKey,但仍包含本机路径,应限制访问。
操作步骤
- 调用
cloudsign_upload_begin。首次使用 create_idempotency_key,恢复使用 resume_upload_id,两者二选一。此时校验文件并创建或查询任务,尚不发送文件字节。 - 调用
cloudsign_upload_transfer。SDK 先执行必填 save 回调;只有上传任务 ID 和文件绑定信息持久保存成功,才允许开始分片。 - SDK 按原布局逐片处理。已确认的片跳过,缺片才取凭证补传,再由平台确认。您的业务代码无需选择存储厂商。
- 全部分片确认后,SDK 提交安装包校验。查询原上传任务,直到 state=succeeded 且取得版本 ID。
- 会话停止后,释放旧会话,用原上传任务 ID 和原文件记录创建恢复会话,不重复调用已停止的 transfer。
运行示例
先将下方 JSON 模板保存到自己的私有目录,替换全部占位值,文件权限设为 0600。首次 upload_id 为 null。配置 CLOUDSIGN_BASE_URL、长期 AccessKey 和 CLOUDSIGN_STORAGE_ORIGIN;创建键从状态文件读取。
{
"app_id": "<自己的完整应用 ID>",
"file_name": "application.ipa",
"source_path": "/srv/my-app/private/application.ipa",
"sha256": "<原始整包 64 位小写 SHA-256>",
"create_key": "<已持久保存的本次创建键>",
"upload_id": null
}命令行示例需要哪些配置
这些变量由自己的进程安全配置注入,不把 Secret 写进命令历史或源码。它们只配置客户端,不选择平台存储厂商。
| 变量 | 如何填写 |
|---|---|
CLOUDSIGN_BASE_URL | 网站 HTTPS 主域名 https://www.onesignios.com。 |
CLOUDSIGN_ACCESS_KEY_ID | 示例使用的长期 AccessKey ID。 |
CLOUDSIGN_ACCESS_KEY_SECRET | 同一组长期凭据的 Secret。 |
CLOUDSIGN_API_CA_FILE | 可选的 API CA 文件;默认使用系统 CA。 |
CLOUDSIGN_STORAGE_ORIGIN | 由独立可信配置确认的精确 HTTPS 文件传输来源,用于限制客户端可访问的目标。 |
CLOUDSIGN_STORAGE_CA_FILE | 可选的文件传输 CA 文件,不能用它关闭证书验证。 |
cmake -S . -B build
cmake --build build -j2
./build/cloudsign_upload_example /srv/my-app/private/upload.json
# 中断后使用同一文件;wait 额外等待服务端校验。
./build/cloudsign_upload_example /srv/my-app/private/upload.json wait查看完整 upload-example.c 源码
/* Trusted-server CLI. Prepare a private durable JSON state file BEFORE running. */
#define _POSIX_C_SOURCE 200809L
#include <cloudsign/openapi.h>
#include <stdio.h>
#ifndef _WIN32
#include <cJSON.h>
#include <openssl/rand.h>
#include <errno.h>
#include <fcntl.h>
#include <stdlib.h>
#include <string.h>
#include <sys/file.h>
#include <sys/stat.h>
#include <unistd.h>
typedef struct {int directory,lock;char name[256];struct stat previous;cJSON *record;} state_file;
static const char *text(const cJSON *o,const char *key){const cJSON *v=cJSON_GetObjectItemCaseSensitive(o,key);return cJSON_IsString(v)?v->valuestring:NULL;}
static int same(const struct stat *a,const struct stat *b){
int common=a->st_dev==b->st_dev&&a->st_ino==b->st_ino&&a->st_size==b->st_size;
#ifdef __APPLE__
return common&&a->st_mtimespec.tv_sec==b->st_mtimespec.tv_sec&&a->st_mtimespec.tv_nsec==b->st_mtimespec.tv_nsec&&a->st_ctimespec.tv_sec==b->st_ctimespec.tv_sec&&a->st_ctimespec.tv_nsec==b->st_ctimespec.tv_nsec;
#else
return common&&a->st_mtim.tv_sec==b->st_mtim.tv_sec&&a->st_mtim.tv_nsec==b->st_mtim.tv_nsec&&a->st_ctim.tv_sec==b->st_ctim.tv_sec&&a->st_ctim.tv_nsec==b->st_ctim.tv_nsec;
#endif
}
static int private_file(const struct stat *s){return S_ISREG(s->st_mode)&&s->st_uid==geteuid()&&(s->st_mode&0777)==0600&&s->st_nlink==1;}
static int open_state(state_file *s,const char *path){
char parent[4097];size_t n=strlen(path);if(!n||n>=sizeof(parent))return 0;memcpy(parent,path,n+1);
char *slash=strrchr(parent,'/');const char *name=slash?slash+1:path;if(!*name||!strcmp(name,".")||!strcmp(name,"..")||strlen(name)>220)return 0;
strcpy(s->name,name);if(slash){if(slash==parent)slash[1]=0;else *slash=0;}else strcpy(parent,".");
s->directory=open(parent,O_RDONLY|O_DIRECTORY|O_CLOEXEC|O_NOFOLLOW);struct stat dir;
if(s->directory<0||fstat(s->directory,&dir)||!S_ISDIR(dir.st_mode)||(dir.st_uid!=geteuid()&&dir.st_uid!=0)||(dir.st_mode&0022))return 0;
char lock[256];snprintf(lock,sizeof(lock),"%s.lock",s->name);s->lock=openat(s->directory,lock,O_RDWR|O_CREAT|O_NOFOLLOW|O_CLOEXEC,0600);struct stat info;
if(s->lock<0||fstat(s->lock,&info)||!private_file(&info)||flock(s->lock,LOCK_EX|LOCK_NB))return 0;
int fd=openat(s->directory,s->name,O_RDONLY|O_CLOEXEC|O_NOFOLLOW);if(fd<0)return 0;
int ok=!fstat(fd,&s->previous)&&private_file(&s->previous)&&s->previous.st_size>0&&s->previous.st_size<=8192;
char bytes[8193];size_t used=0;
while(ok&&used<(size_t)s->previous.st_size){ssize_t got=read(fd,bytes+used,(size_t)s->previous.st_size-used);if(got<0&&errno==EINTR)continue;if(got<=0){ok=0;break;}used+=(size_t)got;}
ok=ok&&!fstat(fd,&info)&&same(&s->previous,&info);close(fd);if(!ok||memchr(bytes,0,used))return 0;bytes[used]=0;
const char *end=NULL;s->record=cJSON_ParseWithLengthOpts(bytes,used+1,&end,1);
if(!cJSON_IsObject(s->record))return 0;
const char *names[]={"app_id","file_name","source_path","sha256","create_key","upload_id","size_bytes"};unsigned seen=0;
for(const cJSON *v=s->record->child;v;v=v->next){unsigned i;for(i=0;i<7;++i)if(!strcmp(v->string,names[i]))break;if(i==7||(seen&(1u<<i)))return 0;seen|=1u<<i;}
const cJSON *upload=cJSON_GetObjectItemCaseSensitive(s->record,"upload_id"),*size=cJSON_GetObjectItemCaseSensitive(s->record,"size_bytes");
return (seen&63)==63&&text(s->record,"app_id")&&text(s->record,"file_name")&&text(s->record,"source_path")&&text(s->record,"sha256")&&text(s->record,"create_key")&&(cJSON_IsNull(upload)||cJSON_IsString(upload))&&(!size||cJSON_IsNumber(size));
}
static int save(void *context,const cloudsign_upload_checkpoint *cp){
state_file *s=context;struct stat old;if(fstatat(s->directory,s->name,&old,AT_SYMLINK_NOFOLLOW)||!same(&s->previous,&old)||!private_file(&old))return 1;
const cJSON *existing=cJSON_GetObjectItemCaseSensitive(s->record,"size_bytes");if(existing&&existing->valuedouble!=(double)cp->size_bytes)return 1;
const char *prior=text(s->record,"upload_id");if(prior&&strcmp(prior,cp->upload_id))return 1;
cJSON *next=cJSON_Duplicate(s->record,1);if(!next)return 1;
cJSON_DeleteItemFromObjectCaseSensitive(next,"upload_id");cJSON_DeleteItemFromObjectCaseSensitive(next,"size_bytes");
if(!cJSON_AddStringToObject(next,"upload_id",cp->upload_id)||!cJSON_AddNumberToObject(next,"size_bytes",(double)cp->size_bytes)){cJSON_Delete(next);return 1;}
char *json=cJSON_PrintUnformatted(next);cJSON_Delete(next);if(!json)return 1;
unsigned char nonce[12];char temporary[64]=".cloudsign-upload-";static const char hex[]="0123456789abcdef";
if(RAND_bytes(nonce,sizeof(nonce))!=1){cJSON_free(json);return 1;}
for(size_t i=0;i<sizeof(nonce);++i){temporary[17+2*i]=hex[nonce[i]>>4];temporary[18+2*i]=hex[nonce[i]&15];}temporary[41]=0;
int fd=openat(s->directory,temporary,O_WRONLY|O_CREAT|O_EXCL|O_CLOEXEC|O_NOFOLLOW,0600),ok=fd>=0;size_t written=0,length=strlen(json);
while(ok&&written<length){ssize_t n=write(fd,json+written,length-written);if(n<0&&errno==EINTR)continue;if(n<=0){ok=0;break;}written+=(size_t)n;}
ok=ok&&!fchmod(fd,0600)&&!fsync(fd);if(fd>=0&&close(fd))ok=0;
ok=ok&&!fstatat(s->directory,s->name,&old,AT_SYMLINK_NOFOLLOW)&&same(&s->previous,&old)&&private_file(&old);
if(ok)ok=!renameat(s->directory,temporary,s->directory,s->name)&&!fsync(s->directory);
unlinkat(s->directory,temporary,0);cJSON_free(json);return ok?0:1;
}
int main(int argc,char **argv){
state_file saved={.directory=-1,.lock=-1};cloudsign_credentials keys={0};cloudsign_client *client=NULL;cloudsign_upload_session *session=NULL;cloudsign_result *result=NULL;
cloudsign_status status=CLOUDSIGN_INVALID_INPUT;int initialized=0,exit_code=1;
if((argc!=2&&argc!=3)||(argc==3&&strcmp(argv[2],"wait"))){fputs("Usage: cloudsign_upload_example PRIVATE_STATE_JSON [wait]\n",stderr);goto done;}
if(!open_state(&saved,argv[1])){fputs("StateFileError\n",stderr);goto done;}
const char *origin=getenv("CLOUDSIGN_BASE_URL"),*storage=getenv("CLOUDSIGN_STORAGE_ORIGIN"),*id=getenv("CLOUDSIGN_ACCESS_KEY_ID"),*secret=getenv("CLOUDSIGN_ACCESS_KEY_SECRET");
if(!origin||!storage||!id||!secret||strlen(id)>=sizeof(keys.access_key_id)||strlen(secret)>=sizeof(keys.access_key_secret))goto done;
strcpy(keys.access_key_id,id);strcpy(keys.access_key_secret,secret);status=cloudsign_global_init();if(status!=CLOUDSIGN_OK)goto done;initialized=1;
cloudsign_options api={.origin=origin,.credentials=&keys,.ca_file=getenv("CLOUDSIGN_API_CA_FILE"),.timeout_ms=15000};status=cloudsign_client_create(&api,&client);cloudsign_credentials_clear(&keys);if(status!=CLOUDSIGN_OK)goto done;
const char *upload=text(saved.record,"upload_id"),*allowed[]={storage};
cloudsign_upload_options options={.app_id=text(saved.record,"app_id"),.source_path=text(saved.record,"source_path"),.file_name=text(saved.record,"file_name"),.expected_sha256=text(saved.record,"sha256"),.create_idempotency_key=upload?NULL:text(saved.record,"create_key"),.resume_upload_id=upload,.allowed_origins=allowed,.allowed_origin_count=1,.ca_file=getenv("CLOUDSIGN_STORAGE_CA_FILE"),.maximum_api_calls=4096,.total_timeout_ms=3600000,.part_timeout_ms=120000,.save=save,.context=&saved};
status=cloudsign_upload_begin(client,&options,&session,&result);if(status!=CLOUDSIGN_OK)goto done;
status=cloudsign_upload_transfer(session,&result);if(status!=CLOUDSIGN_OK)goto done;
if(argc==3){
cJSON *body=cJSON_ParseWithLength(cloudsign_result_json(result),cloudsign_result_json_length(result));const char *state=text(cJSON_GetObjectItemCaseSensitive(body,"data"),"state");int pending=state&&!strcmp(state,"validating");cJSON_Delete(body);
if(pending){cloudsign_result_free(result);result=NULL;cloudsign_param path[]={{"app_id",options.app_id},{"upload_id",cloudsign_upload_id(session)}};cloudsign_request request={.path=path,.path_count=2};cloudsign_wait_options wait={60,2000,120000,NULL,NULL};status=cloudsign_wait_upload(client,&request,&wait,&result);if(status!=CLOUDSIGN_OK)goto done;}
}
cJSON *body=cJSON_ParseWithLength(cloudsign_result_json(result),cloudsign_result_json_length(result));const char *state=text(cJSON_GetObjectItemCaseSensitive(body,"data"),"state");
if(!state){cJSON_Delete(body);status=CLOUDSIGN_INVALID_RESPONSE;goto done;}
printf("%s %s %s\n",cloudsign_result_request_id(result),cloudsign_upload_id(session),state);exit_code=!strcmp(state,"succeeded")?0:2;cJSON_Delete(body);
done:
if(exit_code==1)fprintf(stderr,"%s %s; RequestId: %s\n",cloudsign_status_name(status),cloudsign_result_error_code(result),cloudsign_result_request_id(result));
cloudsign_result_free(result);cloudsign_upload_session_free(session);cloudsign_client_free(client);cloudsign_credentials_clear(&keys);if(initialized)cloudsign_global_cleanup();cJSON_Delete(saved.record);
if(saved.lock>=0)close(saved.lock);if(saved.directory>=0)close(saved.directory);return exit_code;
}
#else
int main(void){fputs("UnsupportedPlatform\n",stderr);return 1;}
#endif
确认结果
| 情况 | 怎样判断 | 下一步 |
|---|---|---|
| 退出 0,state=succeeded | 原包已校验并保存为版本。 | 保存版本 ID;签名或分发按后续业务分别处理。 |
| 退出 2,validating / failed / cancelled | 任务仍在校验,或已经以非成功状态结束。 | 保存原上传任务 ID,继续查询或处理失败原因。 |
| 退出 1 | 配置、传输或检查点保存失败。 | 按错误处理后,从原状态文件恢复,不另建相同上传。 |
进度回调表示已确认分片数,不是安装次数或发布结果。示例只输出 request_id、上传任务 ID 和状态。
参数与详细规则
检查点是您的持久恢复记录,会话是 SDK 本次执行期间的内存对象。两者分开管理,才能在程序重启后继续。
| 参数或对象 | 表示什么 | 使用要点 |
|---|---|---|
| save 回调 | 持久保存上传任务 ID、应用、文件名、大小和整包摘要。 | 完成保存后返回 0;保存失败时不能继续发送文件。 |
| create_idempotency_key | 首次创建本次逻辑上传的稳定键。 | 已拿到上传任务 ID 后按原 ID 恢复,原键仍保留。 |
| session / result | SDK 会话与提交结果。 | 会话和结果分别释放,客户端保留到会话结束。 |
查看完整参数、内存管理与运行边界
| 参数 / 生命周期 | 说明 |
|---|---|
cloudsign_upload_options | app_id、source_path、file_name、expected_sha256 来自可信记录。整包 22 字节–16 GiB,file_name 为 160 UTF-8 字节以内的 .ipa / .apk 名称;不能含路径分隔符或冒号。 |
create_idempotency_key / resume_upload_id | 二选一,创建键 16–64 位字母 / 数字 / 下划线 / 连字符;已创建后使用保存的 上传任务 ID 恢复。原创建键仍需保留用于受理结果不明时查询,不能用于另一份文件。 |
expected_sha256 | 原始整包 64 位小写 SHA-256;与分片 expected_sha256 不同。每次 begin 都重新流式核对,不信任调用方声称文件“未变”。 |
save / progress / cancelled / context | save 必填,返回 0 表示已完成持久化。progress 可选,参数为已确认分片数 / 总片数;不是下载次数或应用发布结果。回调同步且须有界,context 保持有效,不能重入同一客户端或会话。 |
maximum_api_calls | 1–4096,包含 begin、声明、确认探测、取票和最终提交的 API 尝试。达到上限返回 RequestLimitExceeded,不继续请求;不含存储传输。API 与存储均不自动重试。 |
total_timeout_ms / part_timeout_ms | 总预算 1000–86400000 ms,从 begin 起包含哈希、等待调用 transfer、持久化、回调及网络;单片 1000–600000 ms,进一步受剩余总预算限制。API 请求还受原客户端单次超时限制。 |
allowed_origins / ca_file | 独立可信的 1–16 个精确 HTTPS 存储源及可选存储 CA;API CA 由 API 客户端配置。由 SDK 校验平台下发的上传指令,保持凭据隔离;客户端的 DNS 与出口策略由接入方维护。 |
session / receipt / result | begin 的 session 和 error 输出须先为 NULL。成功时 error=NULL;初始 receipt / ID 由会话拥有,getter 借用期间不能释放或修改。transfer 输出 result 由调用方释放。客户端须活到会话结束,两者不能并发使用。 |
运行限制与错误处理
整包哈希用 64 KiB 读取缓冲,保存最多 512 个分片摘要;传输时最多保留一个 32 MiB 快照。固定文件描述符,拒绝最终符号链接 / 非普通文件,持续核对 inode、设备、大小和纳秒修改 / 变更时间;每片还要匹配最初计算的摘要。回调前复制配置;调用期间不要并发修改文件、客户端或结果。同步文件 I/O 和外部回调无法被强制打断,返回后仍检查预算。状态文件由调用方管理,SDK 核心不会擅自写文件。
声明和分片确认键分别为 SHA-256(上传任务 ID:N:分片SHA:declare) 与 SHA-256(上传任务 ID:N:分片SHA:ack),最终提交键为 SHA-256(上传任务 ID:complete),与现有服务端助手规则一致。恢复时同一上传任务 / N / 内容保持原键。API 错误保留安全错误码与 request_id;本地错误会丢弃凭证正文。新增 RequestLimitExceeded / CheckpointFailed / UploadStopped,已有 IntegrityError、FileError、InvalidResponse、InvalidUploadTicket、UploadFailed、Cancelled、DeadlineExceeded 等仍分别检查。
CLI 状态文件与锁的要求
状态文件须已存在,属于当前进程用户,权限为 0600 且只有一个硬链接。父目录由当前用户或 root 所有,组和其他用户不可写。CLI 拒绝符号链接与重复字段,固定父目录并持有独立 0600 .lock 文件的非阻塞排他锁。
检查点先写入随机私有文件,fsync 后原子替换,再 fsync 父目录。CLI 会补入上传任务 ID 和 size_bytes;锁文件保留,其他进程运行时不要删除或替换。SDK 核心不直接写状态文件,持久化由调用方的 save 回调完成。
失败后如何继续
| 情况 | 怎样判断 | 下一步 |
|---|---|---|
| CheckpointFailed | 恢复记录未成功持久保存。 | 修复保存位置或事务后,按原文件与创建键恢复。 |
| UploadStopped / Cancelled / DeadlineExceeded | 本次会话已经停止。 | 释放后,用原上传任务 ID 与文件绑定记录重新开始恢复。 |
| RequestLimitExceeded | 达到本次允许的 API 尝试上限。 | 先核对原任务;明确下一次预算后恢复,避免无界循环。 |
文件助手使用 Linux / POSIX 文件接口。其他系统的支持范围见源码包 README,收到 UnsupportedPlatform 时应停止本次文件操作。网络中断后先核对原记录,不自动开始另一项业务。
CLI 的上传预算为 1 小时、单片 120 秒、API 尝试最多 4096 次;wait 最多 60 次、120 秒,间隔 2 秒。检查点使用 fsync 与原子替换,持有非阻塞排他锁;锁文件保留,不在其他进程运行时删除。同步文件 I/O 和回调须有界,客户端保留到会话结束。