Discord.js：添加用户至私有文本频道的权限问题排查

问题描述 #

尝试通过HTTP接口将已加入服务器的用户添加至私有文本频道时，仅在机器人拥有Administrator权限时功能正常，赋予其他权限组合（包括除Administrator外的全部权限）都会返回403错误（错误码50001，提示Missing Access）。机器人角色已置于服务器角色列表顶部，怀疑权限参数配置是否有问题，当前权限参数如下：

const permissions = {
    allow: "1024",
    deny: "0",
    type: "1",
};

相关实现代码（拥有Administrator权限时可正常运行）：

export async function addUserToPrivateChannel(
  channelId: string,
  userId: string
) {
  const url = `${discordBaseUrl}/channels/${channelId}/permissions/${userId}`;
  const permissions = {
    allow: "1024",
    deny: "0",
    type: "1",
  };

  const options = {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bot ${DISCORD_TOKEN}`,
    },
    body: JSON.stringify(permissions),
  };

  return await discordFetch(url, options);
}


async function discordFetch(url, options) {
  try {
    const response = await fetch(url, options);

    // Log rate limit information
    const rateLimit = response.headers.get("X-RateLimit-Limit");
    const rateLimitRemaining = response.headers.get("X-RateLimit-Remaining");
    const rateLimitReset = response.headers.get("X-RateLimit-Reset");

    if (rateLimitReset) {
      const rateLimitResetDate = new Date(Number(rateLimitReset) * 1000);
      console.log(
        `Rate Limit Reset: ${rateLimitResetDate.toLocaleTimeString()}`
      );
    }
    console.log(`Rate Limit: ${rateLimit}`);
    console.log(`Rate Limit Remaining: ${rateLimitRemaining}`);

    if (!response.ok) {
      const text = await response.text();
      throw new Error(`HTTP error! Status: ${response.status} - ${text}`);
    }

    if (response.status === 204 || response.status === 201) {
      console.log(
        `User added successfully with status code: ${response.status}`
      );
      return { status: response.status }; 
    } else {
      return await response.json();
    }
  } catch (error) {
    console.error("Error with Discord fetch:", error);
    throw error; 
  }
}

请问非Administrator权限下，如何正确配置以实现该功能？

解决方案 #

一、核心权限配置 #

不需要给机器人Administrator权限，但必须同时配置以下两个权限：

• 服务器级别：勾选Manage Roles（管理角色）权限，这是修改用户/角色频道权限条目的基础权限。
• 目标私有频道级别：给机器人分配Manage Channels（管理频道）权限，确保它能修改该频道的权限设置。

注意：如果目标频道的权限设置里明确拒绝了机器人的Manage Channels权限，即使服务器级别有该权限也会失效，需要检查频道的权限覆盖规则。

二、权限参数验证 #

你的现有参数配置是正确的：

• allow: "1024"对应VIEW_CHANNEL权限，是用户访问私有频道的必要权限；
• type: "1"表示操作对象是用户（0为角色），符合需求；
• deny: "0"表示没有拒绝任何权限，无需修改。

如果需要让用户拥有更多频道权限（比如发送消息），可以叠加权限值，例如允许查看+发送消息的话，allow值改为"3072"（1024+2048）。

三、额外检查项 #

1. 确保机器人角色的优先级高于目标用户的所有角色，否则机器人无法修改该用户的频道权限；
2. 检查服务器是否开启了管理操作需2FA的设置，如果开启，机器人的所有者账号必须启用2FA，否则会触发403错误。

内容的提问来源于stack exchange，提问作者user6680