Add comprehensive user troubleshooting guide for credential configuration and common failures

[Copilot]

Description

Added USER_GUIDE_CN.md (1,368 lines) — a comprehensive troubleshooting guide covering credential configuration failures, authentication errors, and deployment scenarios based on deep analysis of all credential provider implementations and exception handling paths.

Document Contents

Core Requirements (Section 2):

• JDK 1.8+ requirement, Maven dependencies
• Network access requirements (STS endpoints, ECS metadata service)
• RAM permissions for each credential type
• 17 environment variables with complete reference table

Quick Start (Section 3):

• Three configuration methods: environment variables, config file (~/.alibabacloud/credentials), programmatic
• Validation examples with expected output

FAQ - 28 Problems Organized by Category (Section 4):

• Credential chain failures: "Unable to load credentials from any providers", config file not applied, empty file path
• ECS RAM role: Metadata service connection refused, role not found, IMDSv1 disabled, refresh failures
• RAM role assumption: Missing required fields, invalid session name format, permission denied
• OIDC: Token file not found/unreadable, missing environment variables
• Network/Timeout: Connection timeouts, STS endpoint unreachable
• Security: AccessKey leak prevention, log sanitization, auto-refresh behavior
• Debugging: Enable debug logging, verify credential source, CI/CD best practices
• Migration: 0.x to 1.x upgrade guide

Each FAQ entry: Problem Symptom → Root Cause (code-based) → Solution (actionable steps)

Reference Tables (Section 5):

• Quick error lookup: 10 common error keywords → instant fix
• Recommended configurations by environment (production/dev/CI-CD)
• Required fields per credential type

Example Error Resolution

Common case: Default credential chain fails

CredentialException: Unable to load credentials from any of the providers in the chain: 
[SystemPropertiesCredentialsProvider: ..., EnvironmentVariableCredentialsProvider: ...]

Root cause: No valid credential source in chain order (system properties → env vars → OIDC → CLI config → profile file → ECS metadata → credentials URI)

Fix: Set environment variables or create ~/.alibabacloud/credentials:

[default]
enable = true
type = access_key
access_key_id = LTAI5t...
access_key_secret = xxx...

You need to complete

• unit tests and/or feature tests
• documentation is changed or added

Original prompt

请全面、深入地阅读当前项目的全部源代码（包括但不限于 README、配置文件、脚本、构建文件、测试用例等，不限于 Python，可能包含 JavaScript、Go、Java、C++、Shell、YAML、JSON 等任意语言或格式），准确理解项目的功能逻辑、架构设计、依赖关系、运行机制及使用方式。

基于对代码的完整分析，请撰写一份面向终端用户的说明文档，核心目标是帮助用户在部署、配置和使用该项目时快速识别、理解并解决常见问题。

文档需包含以下部分，并以 Markdown 格式输出：

1. 项目简介
   简要说明项目用途、核心能力及典型应用场景。

2. 使用前提与环境要求
   明确列出运行该项目所必需的：

   • 操作系统要求（如 Linux/macOS/Windows 版本）
   • 运行时环境（如 Node.js、Python、JDK、.NET、Docker 等）及其最低版本
   • 系统依赖（如特定库、命令行工具、内核特性等）
   • 网络或权限要求（如需要外网访问、root 权限、API 密钥等）

3. 快速开始指南
   提供清晰、可复现的步骤，包括：

   • 安装/构建方法（如 npm install、make、go build、docker-compose up 等）
   • 配置说明（如环境变量、配置文件模板）
   • 启动与验证命令（附带预期输出示例）

4. 常见问题解答（FAQ） —— 重点部分
   请基于代码中所有可能引发失败或异常的逻辑路径，主动推断用户在真实使用中可能遇到的问题，并以问答形式详尽列出。每个问题应包含：

   • 问题现象：用户可能看到的错误信息、程序行为异常或日志内容（可引用具体报错）
   • 根本原因：结合代码逻辑说明为何会出现此问题（如：未处理空输入、配置字段缺失、文件路径硬编码、权限检查失败、超时阈值过小、特定平台不兼容等）
   • 解决方案或规避建议：提供具体、可操作的修复步骤或最佳实践

   特别注意：

   • 重点关注所有异常处理分支（如 try/catch、panic/recover、if err != nil、assert、错误码返回、日志警告等）
   • 分析边界条件、非法输入、缺失依赖、环境差异等易错场景
   • 即使官方文档或 README 未提及，只要代码中存在潜在使用陷阱，就必须纳入 FAQ
   • 测试test case通常也是为了验证代码及异常分支，也需要重点分析

文档语言应简洁明了、面向用户，避免堆砌技术细节，重点突出“问题—原因—解决”链条，确保非开发者也能理解并操作。

最终输出必须为结构清晰、排版规范的 Markdown 文档。

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[CodeSpaceiiii]

test