{"id":17922711,"url":"https://github.com/overtrue/laravel-qcloud-federation-token","last_synced_at":"2026-02-25T09:03:19.426Z","repository":{"id":54491871,"uuid":"451495157","full_name":"overtrue/laravel-qcloud-federation-token","owner":"overtrue","description":"QCloud COS FederationToken generator for Laravel.","archived":false,"fork":false,"pushed_at":"2025-03-18T10:59:19.000Z","size":53,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-18T11:41:04.472Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/overtrue.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["overtrue"]}},"created_at":"2022-01-24T14:23:20.000Z","updated_at":"2025-03-18T10:59:08.000Z","dependencies_parsed_at":"2024-10-28T20:40:38.242Z","dependency_job_id":"5218f7fe-d13c-4a62-a139-b59c5d8aa078","html_url":"https://github.com/overtrue/laravel-qcloud-federation-token","commit_stats":{"total_commits":36,"total_committers":2,"mean_commits":18.0,"dds":0.02777777777777779,"last_synced_commit":"eed492157a3c80859cf1f275df860a94ea4228e4"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":"overtrue/laravel-package","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overtrue%2Flaravel-qcloud-federation-token","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overtrue%2Flaravel-qcloud-federation-token/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overtrue%2Flaravel-qcloud-federation-token/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overtrue%2Flaravel-qcloud-federation-token/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/overtrue","download_url":"https://codeload.github.com/overtrue/laravel-qcloud-federation-token/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245198763,"owners_count":20576438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-28T20:40:32.804Z","updated_at":"2026-02-25T09:03:19.420Z","avatar_url":"https://github.com/overtrue.png","language":"PHP","funding_links":["https://github.com/sponsors/overtrue"],"categories":[],"sub_categories":[],"readme":"Laravel 腾讯云联合身份临时访问凭证生成器\n---\n\n![Laravel Octane Ready Status](https://img.shields.io/badge/Octance-ready-green?style=flat-square)\n![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/overtrue/laravel-qcloud-federation-token?style=flat-square)\n![GitHub License](https://img.shields.io/github/license/overtrue/laravel-qcloud-federation-token?style=flat-square)\n![Packagist Downloads](https://img.shields.io/packagist/dt/overtrue/laravel-qcloud-federation-token?style=flat-square)\n\nLaravel [腾讯云联合身份临时访问凭证](https://cloud.tencent.com/document/product/1312/48195) 生成器，主要用于下发腾讯云联合身份临时访问凭证，比如前端直传等场景。\n\n[![Sponsor me](https://github.com/overtrue/overtrue/blob/master/sponsor-me-button-s.svg?raw=true)](https://github.com/sponsors/overtrue)\n\n开始之前，请您仔细阅读并理解一下官方文档：\n\n- [获取联合身份临时访问凭证](https://cloud.tencent.com/document/product/1312/48195)\n- [COS API 授权策略使用指引](https://cloud.tencent.com/document/product/436/31923)\n- [条件键说明及使用示例](https://cloud.tencent.com/document/product/436/71307)\n- [CAM 策略语法](https://cloud.tencent.com/document/product/598/10603)\n- [临时证书](https://cloud.tencent.com/document/api/1312/48198#Credentials)\n- [API Doctor(使用诊断)](https://console.cloud.tencent.com/api/diagnosis)\n- [COS 自助诊断工具](https://console.cloud.tencent.com/cos/diagnose)\n\n## 安装\n\n```shell\n$ composer require overtrue/laravel-qcloud-federation-token -vvv\n```\n\n### 配置\n\n你可以通过以下命令将配置文件写入 `config/federation-token.php`:\n\n```php\n$ php artisan vendor:publish --provider=\"Overtrue\\\\LaravelQCloudFederationToken\\\\QCloudFederationTokenServiceProvider\"\n```\n\n**config/federation-token.php**\n\n```php\nreturn [\n    // 默认配置，strategies 下的每一个策略将合并此基础配置\n    'default' =\u003e [\n        'secret_id' =\u003e env('QCLOUD_COS_SECRET_ID', ''),\n        'secret_key' =\u003e env('QCLOUD_COS_SECRET_KEY', ''),\n        'region' =\u003e env('QCLOUD_COS_REGION', 'ap-guangzhou'),\n        \"effect\" =\u003e \"allow\",\n        \n        // 全局变量，会被替换到所有策略中\n        'variables' =\u003e [\n            'uid' =\u003e env('QCLOUD_COS_APP_ID'),\n            'region' =\u003e env('QCLOUD_COS_REGION', 'ap-guangzhou'),\n            //...\n        ],\n    ],\n    // strategies\n    'strategies' =\u003e [\n        // 策略名称，比如：image/avatar...\n        'avatar' =\u003e [\n            // 策略名称，可选\n            'name' =\u003e 'avatar',\n            \n            // 临时凭证过期时间\n            'expires_in' =\u003e 1800,\n            \n            // 将与默认配置合并\n            'variables' =\u003e [\n                'appid' =\u003e env('QCLOUD_COS_APP_ID'),\n                'bucket' =\u003e env('QCLOUD_COS_BUCKET', ''),\n                //...\n            ],\n            \n            // Statement 请参考：https://cloud.tencent.com/document/product/598/10603\n            \"statements\" =\u003e [\n                [\n                    \"action\" =\u003e [\n                        // 这里建议不要随便修改，分片上传需要用到这些\n                        'cos:ListParts',\n                        'cos:PutObject',\n                        'cos:PostObject',\n                        'cos:InitiateMultipartUpload',\n                        'cos:UploadPart',\n                        'cos:CompleteMultipartUpload',\n                        'cos:AbortMultipartUpload',\n                        'cos:ListMultipartUploads',\n                    ],\n                    \"resource\" =\u003e [\n                        \"qcs::cos:ap-beijing:uid/\u003cappid\u003e:\u003cbucket\u003e-\u003cappid\u003e/\u003cdate\u003e/\u003cuuid\u003e/*\",\n                    ],\n                    'condition' =\u003e [\n                        'string_equal' =\u003e [\n                            'cos:x-cos-forbid-overwrite' =\u003e 'true', // 禁止覆盖\n                        ],\n                    ],\n                ]\n            ],\n            'headers' =\u003e [\n                // statements 包含 x 类型的 condition 需要告诉客户端传递 header\n                'x-cos-forbid-overwrite' =\u003e true,\n            ]\n        ],\n    ],\n];\n```\n\n\n配置语法请参考：https://cloud.tencent.com/document/product/598/10603\n\n你可以根据使用场景配置多个策略，然后按策略分发访问凭证。\n\n\u003e **Warning**\n\u003e \n\u003e 注意：`condition` 中使用 `cos:content-type` 记得 urlencode, 不然遇到带+号的 MIME 将会失效，比如 `image/svg+xml`。\n\n### 安全提醒\n\n临时 token 规则配置不合理，可能会造成安全问题，请谨慎配置，请严格检查如下：\n\n- 配置前请仔细阅读：[《用于前端直传 COS 的临时密钥安全指引》](https://cloud.tencent.com/document/product/436/40265)\n- 策略有限制最大长度，不建议把策略配置得太多。\n- 凭证生命周期不要设置过长。\n- 避免使用主账号来生成凭证，专用的限制登录的 API 子账号。\n- 按照[《条件键说明及使用示例》](https://cloud.tencent.com/document/product/436/71307) 添加请求限制如上传大小和类型等。\n- 将账号权限控制在尽量小的范围内，避免越权操作。\n\n### 变量替换\n\n在配置中难免会用到各种上下文变量或者一些动态 resouce 路径等，你可以在配置中指定 `variables` 变量来实现变量替换，例如：\n\n\u003e 仅 principal 和 resource 中的变量可以替换，其他变量不支持替换。\n\n```php\n// config/federation-token.php\n\u003c?php\n\nreturn [\n    // 默认配置，strategies 下的每一个策略将合并此基础配置\n    'default' =\u003e [\n        'secret_id' =\u003e env('QCLOUD_COS_SECRET_ID'),\n        'secret_key' =\u003e env('QCLOUD_COS_SECRET_KEY'),\n        'region' =\u003e env('QCLOUD_COS_REGION', 'ap-guangzhou'),\n        \"effect\" =\u003e \"allow\",\n        \n        // 全局变量，会被替换到所有策略中\n        'variables' =\u003e [\n            'region' =\u003e env('QCLOUD_COS_REGION', 'ap-guangzhou'),\n            //...\n        ],\n    ],\n    // strategies\n    'strategies' =\u003e [\n        // 请参考：https://cloud.tencent.com/document/product/598/10603\n        'avatar' =\u003e [\n            // 将与默认配置合并\n            'variables' =\u003e [\n                'appid' =\u003e env('QCLOUD_COS_APP_ID'),\n                'bucket' =\u003e env('QCLOUD_COS_BUCKET'),\n                //...\n            ],\n            \"statements\" =\u003e [\n                [\n                    \"action\" =\u003e [\n                        'cos:ListParts',\n                        'cos:PutObject',\n                        'cos:PostObject',\n                        'cos:InitiateMultipartUpload',\n                        'cos:UploadPart',\n                        'cos:CompleteMultipartUpload',\n                        'cos:AbortMultipartUpload',\n                        'cos:ListMultipartUploads',\n                    ],\n                    \"resource\" =\u003e [\n                        \"qcs::cos:ap-beijing:uid/\u003cappid\u003e:\u003cbucket\u003e-\u003cappid\u003e/\u003cdate\u003e/\u003cuuid\u003e/*\",\n                    ],\n                ]\n            ],\n        ],\n    ],\n];\n```\n\n以上配置将会生成如下结果：\n\n```json\n{\n    \"effect\": \"allow\",\n    \"action\": [\n        \"cos:PutObject\",\n        \"cos:GetObject\",\n    ],\n    \"resource\": [\n        \"qcs::cos:ap-beijing:uid/12278900:example-12278900/20220202/bbeae9bb-d650-46f9-aab3-f4171a1bfdea/*\"\n    ]\n}\n```\n\n### 内置变量如下\n\n- `\u003cuuid\u003e` - UUID 例如：`ca007813-4a49-4d5a-afab-abae18a969a5`\n- `\u003ctimestamp\u003e` - 当前时间戳，例如：`1654485526`\n- `\u003crandom\u003e` - 随机字符串，16 位，例如：`Bbq6gkXXIPyCDsEL`\n- `\u003crandom:32\u003e` - 随机字符串，32 位，例如：`FykbMqi6GT6JHiyv6E2xqUeo3CZLPjo7`\n- `\u003cdate\u003e` - 日期，例如：`20220606`\n- `\u003cYmd\u003e` - 日期，例如：`20220606`\n- `\u003cYmdHis\u003e` - 日期时间（年月日时分秒），例如：`20220606031846`\n- `\u003cY\u003e` - 年，例如：`2022`\n- `\u003cm\u003e` - 月，例如：`06`\n- `\u003cd\u003e` - 日，例如：`06`\n- `\u003cH\u003e` - 时，例如：`03`\n- `\u003ci\u003e` - 分，例如：`18`\n- `\u003cs\u003e` - 秒，例如：`46`\n\n## 使用\n\n```php\nuse Overtrue\\LaravelQCloudFederationToken\\FederationToken;\n\n// 使用默认策略（配置项 strategies 中第一个）\n$token = FederationToken::createToken();\n\n// 或者指定策略\n$token = FederationToken::strategy('avatar')-\u003ecreateToken();\n\n$token-\u003etoArray();\n\n// 'credentials' =\u003e [\n//     'token' =\u003e 'kTRtHpOSOCUzTVWmzlPKweHffXjT9Izo7b61a142d6b56d31c0a7ace4d22bcff3zpbsXKTIrCo43dRRh7bDIKE1ZOE1KRYHEm0KNLjWG_aSF63YoQWchg',\n//     'tmp_secret_id' =\u003e 'AKIDw7dwZbmFSup9CnAOraJ7skiPMybaV3WPP5B4oVMCIL5kLyphV_3IyAHFJ5QMCjE6',\n//     'tmp_secret_key' =\u003e '/lvEo280/AlGt4orjDl9tWLIOMl5nkexS5Pg+xys7ps=',\n// ],\n// 'expired_at' =\u003e 1547696355,\n```\n\n如果你需要获取生成 token 的配置信息，你可以使用 `getStatements` 方法：\n\n```php\n$token-\u003egetStatements();\n```\n\n格式请参考： https://cloud.tencent.com/document/product/1312/48195\n\n### 字符限制问题\n\n对于单次策略请求，官方限制策略总字符数为 1000 字符，稍微复杂一点就会超过这个限制，建议做法：\n\n- 在控制台配置策略，写法一样，也有可视化配置界面，不限制字符数\n- 在 API 侧配置简单的基础策略\n\n请求时将会产生交集结果，所以二者结合，既保证了安全，也避免了 API 断字符限制问题。\n\n### 事件\n\n| **Event**                                                   | **Description** |\n|-------------------------------------------------------------|--------------|\n| `Overtrue\\LaravelQcloudFederationToken\\Events\\TokenCreated` | token 生成时触发  |\n\n## :heart: 赞助我\n\n[![Sponsor me](https://github.com/overtrue/overtrue/blob/master/sponsor-me.svg?raw=true)](https://github.com/sponsors/overtrue)\n\n如果你喜欢我的项目并想支持它，[点击这里 :heart:](https://github.com/sponsors/overtrue)\n\n## 贡献代码\n\n你可以通过以下方式参与贡献:\n\n1. 通过 [issue tracker](https://github.com/overtrue/laravel-package/issues) 提交 Bug；\n2. 通过 [issue tracker](https://github.com/overtrue/laravel-package/issues) 回答问题或修复 Bug；\n3. 通过 Pull Request 增加新特性或优化文档。\n\n_代码贡献过程不需要很正式。你只需要确保你遵循 PSR-0、PSR-1 和 PSR-2 的编码准则。任何新的代码贡献都必须附带对应的单元测试。_\n\n## Project supported by JetBrains\n\nMany thanks to Jetbrains for kindly providing a license for me to work on this and other open-source projects.\n\n[![](https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.svg)](https://www.jetbrains.com/?from=https://github.com/overtrue)\n\n## PHP 扩展包开发\n\n\u003e 想知道如何从零开始构建 PHP 扩展包？\n\u003e\n\u003e 请关注我的实战课程，我会在此课程中分享一些扩展开发经验 —— [《PHP 扩展包实战教程 - 从入门到发布》](https://learnku.com/courses/creating-package)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fovertrue%2Flaravel-qcloud-federation-token","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fovertrue%2Flaravel-qcloud-federation-token","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fovertrue%2Flaravel-qcloud-federation-token/lists"}