Tencent Cloud COS

About 10 minutes and no money: this is how you prepare one bucket and one key pair limited to that bucket in Tencent Cloud COS for Guyun.

This is the official Guyun guide. A cloud account is all you need to start; you do not have to understand Tencent Cloud's permission model first — just follow along.

What you need

A Tencent Cloud account (a personal one is fine). Sign in to the console as the root account for all of the steps below.
The region the bucket will live in, for example ap-guangzhou. The same region goes into Guyun later, so both must match.
A bucket name you have thought of; your account's APPID is appended to its end automatically.
No other service to activate, no domain and no ICP filing.

You pay for what you use: object storage has no activation fee, an empty bucket costs almost nothing, and charges afterwards come from stored bytes, request counts and public traffic. If you already have a bucket and a key pair, skip the first three steps and go straight to "Copy these four values".

Step by step

Step 1

Create the bucket
- Open the Tencent Cloud console, go to COS (object storage) and choose Bucket list in the sidebar, then Create bucket.
- Give it any name (lowercase letters, digits and hyphens) and pick the region you want — ap-guangzhou, for example. Use the same region that you will enter in Guyun.
- Set the access mode to private read/write, leave the other options alone and create it.
- Tencent Cloud appends your APPID to the bucket name, giving something like my-photos-1234567890. Copy the whole name, suffix included — copying only the first part is the most common reason Guyun cannot reach the bucket.
- The APPID is a string of digits (1234567890 in these examples). You can see it under account information in the console, or at the end of any bucket you already have.
- Guyun is the only provider that asks for one extra field: put the APPID in its own APPID field and the plain name in the bucket field — Guyun appends the suffix for you, turning my-photos into my-photos-1234567890. If the name you paste already carries the suffix, it is not appended twice.
Step 2

Create a sub-account and its key
- As the root account, open CAM (access management) → Users → User list and choose Create user.
- Tick programmatic access only — do not tick console login: Guyun needs nothing but a key pair.
- Copy the SecretId and SecretKey of that sub-user. The secret is shown once and is gone once you leave the page, so save both values now.
- Do not use the root account's key: it covers your whole account, while Guyun needs one bucket.
Step 3

Give the sub-account permission
- First, the thing that trips everyone up: GetService and PutBucket in CAM are actions, not policy names — searching the policy list for them finds nothing. To use them you need a custom policy.
- Do this as the root account: CAM → Policies → Create custom policy → create by policy syntax → start from the blank template.
- Paste the JSON below into the policy content and replace the bucket name and APPID in it (your-bucket-name-1234567890, 1234567890 and the region ap-guangzhou are all made-up examples).
- The policy grants two levels at once: the first statement is account-level and allows listing the buckets in your account and creating new ones (a bucket that does not exist yet cannot be named in a resource path, hence *); the second statement is bucket-level and covers your one bucket, where cos:* hands over everything inside it.
- The policy deliberately leaves out deleting buckets — Guyun does not need it. It creates a bucket and puts things in it.
- If you only want to use a bucket you already have and would rather the app did not create one, delete the first statement and keep the bucket-level one.
- After saving, attach the policy to that sub-user (CAM → Users → the user → Associate policies).
Step 4

Fill it in, then choose Test connection & save
- Back in Guyun, open Add storage, pick Tencent Cloud COS as the provider and the same region you chose in the console.
- Fill in the values in this order: APPID, bucket name, region, endpoint, and the key pair (SecretId and SecretKey).
- Choose Test connection & save. It only lists the bucket's root directory — nothing is uploaded or deleted.

What the sub-account needs: one CAM custom policy

Replace your-bucket-name, 1234567890 and the region with your own bucket name, APPID and region. The policy deliberately does not include deleting buckets.

json

{
  "version": "2.0",
  "statement": [
    { "effect": "allow", "action": ["cos:GetService", "cos:PutBucket"], "resource": ["*"] },
    { "effect": "allow", "action": ["cos:*"],
      "resource": ["qcs::cos:ap-guangzhou:uid/1234567890:your-bucket-name-1234567890/*"] }
  ]
}

Where to paste it: CAM console → Policies → Create custom policy → create by policy syntax → blank template. The first statement allows listing and creating buckets; delete it if you only want to use a bucket you already have.

Tencent Cloud ships ready-made policies too

If you would rather not write a policy, you can attach these three that Tencent Cloud already provides — the effect is much the same:

QcloudCOSGetServiceAccess — list the buckets in the account.
QcloudCOSBucketConfigRead / QcloudCOSBucketConfigWrite — read and write bucket configuration; Write also covers creating buckets.
Their names do not look like actions, so searching the policy list for GetService or PutBucket finds nothing. Search for these three names instead.

What a real account showed

cos:GetService, cos:PutBucket and cos:DeleteBucket also work when you put them in the bucket-scoped statement instead of the * one.

cos:DeleteBucket still only applies to the bucket you scoped it to: any other bucket in the account is refused. Even so, Guyun does not need permission to delete buckets.

The console's access domain is not the endpoint

Once the bucket exists, its overview shows an access domain shaped like https://my-photos-1234567890.cos.ap-guangzhou.myqcloud.com — the bucket name is already the first part of the host, because that address is meant for browsers.

Guyun wants the service endpoint, shaped like https://cos.ap-guangzhou.myqcloud.com, with no bucket name in it; the bucket name goes in its own field.

Paste the access domain into the endpoint field and Guyun will try to reach an address that does not exist, so the connection test fails.

Copy these four values

These go into the matching fields on Guyun's "Add storage" screen (Tencent Cloud COS has one extra field, APPID):

This value	Where it goes in Guyun
Bucket name The full name from the console, including the `-APPID` suffix, e.g. `my-photos-1234567890`.	Bucket name
APPID The digits at the end of the bucket name, e.g. `1234567890` — under account information in the console, or at the end of any bucket you have.	APPID
Region The region code the bucket lives in, e.g. `ap-guangzhou`.	Region
Endpoint The service endpoint, e.g. `https://cos.ap-guangzhou.myqcloud.com` (replace `ap-guangzhou` with your region) — without the bucket name.	Endpoint
Key The SecretId and SecretKey of the sub-user you just created (not the root account's).	SecretId and SecretKey

How to tell it worked

The connection test passes, which means the key can read this bucket — Guyun only lists the root directory, so nothing inside is touched.
The storage then appears in Guyun's list, and you can open it to see the files in the bucket.
If the test answers AccessDenied, the bucket name usually lost its APPID suffix or the key is not allowed on that bucket. If it complains about the address, the access domain was probably used as the endpoint.

Go back to Guyun and choose Test connection & save.

Common errors

The failures Tencent Cloud COS produces most often, and where to look first.

What you see / error code	What it means	What to do
403 `AccessDenied` (bucket name mismatch)	The name is incomplete: only the first part was copied, without the `-APPID` suffix, so the bucket Guyun looked for does not exist or is not yours.	Copy the whole bucket name from the console, e.g. `my-photos-1234567890`, or put the APPID in Guyun's APPID field and let Guyun append it.
403 `AccessDenied` (key not allowed)	The name is right, but this key was never granted that bucket — the policy was not created, not attached to the sub-user, or still names the example bucket.	Check in CAM: is the policy attached to that sub-user, and does its resource path carry your own bucket name and APPID?
`SignatureDoesNotMatch`	The signature does not match: the SecretKey was copied wrongly (a stray space or a missing character), or the bucket name, region or endpoint differs from the real one.	Copy the SecretKey again, then check the bucket name, region and endpoint field by field.
`InvalidAccessKeyId`	That SecretId does not exist — usually a copy error, or a key that has been deleted, disabled or rotated away.	Create a new key pair for that sub-user in CAM and replace both values in Guyun.
SecretKey shown once and not saved	The secret is displayed once when it is created; leave the page and it is gone for good.	There is nothing to recover: create a new key pair for that sub-user in CAM and replace both values in Guyun.
Connection fails with a domain or network error	The console's access domain was used as the endpoint — that address already contains the bucket name (`https://my-photos-1234567890.cos.ap-guangzhou.myqcloud.com`).	Use the service endpoint `https://cos.ap-guangzhou.myqcloud.com` instead, and put the bucket name in the bucket field.
The connection test passes but uploads fail	The test only lists the root directory; being able to read does not mean you can write.	Check in CAM that the bucket-level statement covers writes (the `cos:*` above covers everything), then upload a small file to try.

After changing anything, come back to Guyun and test the connection again — it only saves once the test passes.