> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # Alibaba Cloud OSS > Configure the Alibaba Cloud OSS connector with a least-privilege RAM AccessKey and a narrow bucket prefix. Use the Alibaba Cloud OSS connector to index approved files from Object Storage Service. Create one connector per business knowledge directory, and restrict the RAM policy to the exact bucket and prefix that AIvis should read. ## What You Need | Item | Requirement | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bucket | A private OSS bucket in the region that AIvis can reach. | | Prefix | A non-empty object prefix, such as `knowledge/` or `projects/legal/`. AIvis trims leading `/`; do not use the whole bucket unless it is already curated. | | Region | The OSS region ID, such as `cn-hangzhou` or `cn-shanghai`. | | Credential | A RAM user AccessKey ID and AccessKey Secret with read-only access to the target prefix. | | Endpoint | Usually leave empty. AIvis derives `https://oss-{region}.aliyuncs.com`; use a custom endpoint only when required by your network path or CNAME policy. | OSS stores objects in a flat key space. Console folders are simulated by object-key prefixes and `/` delimiters. Granting access to a "folder" means granting access to every object whose key starts with that prefix. ## Prepare Alibaba Cloud 1. Sign in to Alibaba Cloud and open **RAM**. 2. Create a RAM user dedicated to AIvis, such as `aivis-oss-reader`. 3. Enable programmatic access and create an AccessKey pair for that RAM user. 4. Save the AccessKey ID and AccessKey Secret immediately. Alibaba Cloud shows the AccessKey Secret only when the pair is created. 5. Open the target OSS bucket and confirm its region, for example `cn-hangzhou`. 6. Upload approved files under a dedicated prefix, for example `knowledge/`. ## Minimum RAM Policy Grant only list and read access. The list permission is scoped by `oss:Prefix`; object reads are scoped by the object resource path. ```json { "Version": "1", "Statement": [ { "Effect": "Allow", "Action": "oss:ListObjects", "Resource": "acs:oss:*:*:aivis-docs", "Condition": { "StringLike": { "oss:Prefix": [ "knowledge/", "knowledge/*" ] } } }, { "Effect": "Allow", "Action": [ "oss:GetObject" ], "Resource": "acs:oss:*:*:aivis-docs/knowledge/*" } ] } ``` Do not grant `oss:PutObject`, `oss:DeleteObject`, bucket administration, or broad `oss:*` permissions. If objects use server-side encryption with KMS, confirm whether the RAM identity also needs `kms:Decrypt` for reads. ## Credential Fields Create an Alibaba Cloud OSS credential in AIvis: | AIvis Field | Value | | ------------------------------ | ----------------------------------------------------------------------------------------- | | Key ID / Access Key ID | RAM user AccessKey ID. | | Secret key / Secret Access Key | AccessKey Secret paired with the AccessKey ID. | | Session Token | Leave empty for a permanent AccessKey. Fill it only when using temporary STS credentials. | Rotate the key through RAM if it was shared, lost, or created with excessive permissions. ## Connector Fields | AIvis Field | Example | Notes | | --------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- | | Connector name | `Alibaba Cloud OSS knowledge` | Use a name that identifies the bucket and business scope. | | Bucket Name | `aivis-docs` | Bucket name only, not an `oss://` URL. | | Prefix | `knowledge/` | Must be non-empty. Use a trailing `/` for folder-like scopes. | | Region | `cn-hangzhou` | Lowercase region ID. | | Custom Endpoint URL | Leave empty or `https://oss-cn-hangzhou.aliyuncs.com` | Optional. Must include `https://` and no credentials, query, or fragment. | | ACL limitation confirmation | Checked | Object ACLs are not synchronized into AIvis search permissions. | | Document access | Prefer **Private** and assign users or groups. | Split prefixes/connectors by audience. | The connector uses S3-compatible signed requests with virtual-hosted addressing. If your bucket is in a Chinese mainland region affected by Alibaba Cloud endpoint or CNAME policy changes, configure a valid custom endpoint and confirm it works from the AIvis worker network. ## Verify 1. Confirm the credential validates. 2. Create the connector with a small prefix such as `knowledge/test/`. 3. Run one index attempt and confirm only objects under that prefix appear. 4. Search for a known title or sentence from an uploaded file. 5. Confirm unselected prefixes and sensitive files are absent. 6. Test as an unauthorized AIvis user and confirm private connector content is not searchable. ## Troubleshooting | Symptom | Likely cause and action | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Credential is invalid | AccessKey ID and Secret do not belong to the same RAM user, the Secret was copied incorrectly, or the key is disabled. Create or rotate the RAM AccessKey. | | Bucket cannot be found | Bucket name, region, or endpoint does not match the bucket. Check the OSS bucket region and endpoint. | | Objects cannot be listed | The RAM policy is missing `oss:ListObjects` on the bucket or the `oss:Prefix` condition excludes the configured prefix. | | Objects are listed but cannot be read | The RAM policy is missing `oss:GetObject` for `bucket/prefix/*`, or encrypted objects require additional decrypt permission. | | Too many files are indexed | Prefix is too broad. Use a business directory such as `knowledge/` and mirror that prefix in RAM policy. | | Users can search files they should not access | OSS object ACLs are not synchronized to AIvis. Use private document access or split connectors by audience. | ## Related Official Documentation * [Alibaba Cloud OSS RAM policy access control](https://www.alibabacloud.com/help/en/oss/user-guide/access-control-base-on-ram-policy) * [Alibaba Cloud OSS regions and endpoints](https://www.alibabacloud.com/help/en/oss/user-guide/regions-and-endpoints) * [Alibaba Cloud RAM AccessKey pairs](https://www.alibabacloud.com/help/en/ram/user-guide/create-an-accesskey-pair) * [Alibaba Cloud OSS ListObjects](https://www.alibabacloud.com/help/en/oss/developer-reference/listobjects) * [Alibaba Cloud OSS GetObject](https://www.alibabacloud.com/help/en/oss/developer-reference/getobject)